lib/ibm_watson/speech_to_text_v1.rb
def create_job(audio:, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, content_type: nil)
      raise ArgumentError.new("audio must be provided") if audio.nil?

      headers = {
        "Content-Type" => content_type
      }
      sdk_headers = Common.new.get_sdk_headers("speech_to_text", "V1", "create_job")
      headers.merge!(sdk_headers)

      params = {
        "model" => model,
        "callback_url" => callback_url,
        "events" => events,
        "user_token" => user_token,
        "results_ttl" => results_ttl,
        "language_customization_id" => language_customization_id,
        "acoustic_customization_id" => acoustic_customization_id,
        "base_model_version" => base_model_version,
        "customization_weight" => customization_weight,
        "inactivity_timeout" => inactivity_timeout,
        "keywords" => keywords.to_a,
        "keywords_threshold" => keywords_threshold,
        "max_alternatives" => max_alternatives,
        "word_alternatives_threshold" => word_alternatives_threshold,
        "word_confidence" => word_confidence,
        "timestamps" => timestamps,
        "profanity_filter" => profanity_filter,
        "smart_formatting" => smart_formatting,
        "speaker_labels" => speaker_labels,
        "customization_id" => customization_id,
        "grammar_name" => grammar_name,
        "redaction" => redaction
      }

      data = audio

      method_url = "/v1/recognitions"

      response = request(
        method: "POST",
        url: method_url,
        headers: headers,
        params: params,
        data: data,
        accept_json: true
      )
      response
    end
def create_job(audio:, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, content_type: nil)
      raise ArgumentError.new("audio must be provided") if audio.nil?

      headers = {
        "Content-Type" => content_type
      }
      sdk_headers = Common.new.get_sdk_headers("speech_to_text", "V1", "create_job")
      headers.merge!(sdk_headers)

      params = {
        "model" => model,
        "callback_url" => callback_url,
        "events" => events,
        "user_token" => user_token,
        "results_ttl" => results_ttl,
        "language_customization_id" => language_customization_id,
        "acoustic_customization_id" => acoustic_customization_id,
        "base_model_version" => base_model_version,
        "customization_weight" => customization_weight,
        "inactivity_timeout" => inactivity_timeout,
        "keywords" => keywords.to_a,
        "keywords_threshold" => keywords_threshold,
        "max_alternatives" => max_alternatives,
        "word_alternatives_threshold" => word_alternatives_threshold,
        "word_confidence" => word_confidence,
        "timestamps" => timestamps,
        "profanity_filter" => profanity_filter,
        "smart_formatting" => smart_formatting,
        "speaker_labels" => speaker_labels,
        "customization_id" => customization_id,
        "grammar_name" => grammar_name,
        "redaction" => redaction
      }

      data = audio

      method_url = "/v1/recognitions"

      response = request(
        method: "POST",
        url: method_url,
        headers: headers,
        params: params,
        data: data,
        accept_json: true
      )
      response
    end
@!method create_job(audio:, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, content_type: nil)
 Create a job.
 Creates a job for a new asynchronous recognition request. The job is owned by the
   instance of the service whose credentials are used to create it. How you learn the
   status and results of a job depends on the parameters you include with the job
   creation request:
   * By callback notification: Include the `callback_url` parameter to specify a URL
   to which the service is to send callback notifications when the status of the job
   changes. Optionally, you can also include the `events` and `user_token` parameters
   to subscribe to specific events and to specify a string that is to be included
   with each notification for the job.
   * By polling the service: Omit the `callback_url`, `events`, and `user_token`
   parameters. You must then use the **Check jobs** or **Check a job** methods to
   check the status of the job, using the latter to retrieve the results when the job
   is complete.

   The two approaches are not mutually exclusive. You can poll the service for job
   status or obtain results from the service manually even if you include a callback
   URL. In both cases, you can include the `results_ttl` parameter to specify how
   long the results are to remain available after the job is complete. Using the
   HTTPS **Check a job** method to retrieve results is more secure than receiving
   them via callback notification over HTTP because it provides confidentiality in
   addition to authentication and data integrity.

   The method supports the same basic parameters as other HTTP and WebSocket
   recognition requests. It also supports the following parameters specific to the
   asynchronous interface:
   * `callback_url`
   * `events`
   * `user_token`
   * `results_ttl`

   You can pass a maximum of 1 GB and a minimum of 100 bytes of audio with a request.
   The service automatically detects the endianness of the incoming audio and, for
   audio that includes multiple channels, downmixes the audio to one-channel mono
   during transcoding. The method returns only final results; to enable interim
   results, use the WebSocket API.

   **See also:** [Creating a
   job](https://cloud.ibm.com/docs/services/speech-to-text/async.html#create).

   ### Streaming mode

    For requests to transcribe live audio as it becomes available, you must set the
   `Transfer-Encoding` header to `chunked` to use streaming mode. In streaming mode,
   the service closes the connection (status code 408) if it does not receive at
   least 15 seconds of audio (including silence) in any 30-second period. The service
   also closes the connection (status code 400) if it detects no speech for
   `inactivity_timeout` seconds of streaming audio; use the `inactivity_timeout`
   parameter to change the default of 30 seconds.

   **See also:**
   * [Audio
   transmission](https://cloud.ibm.com/docs/services/speech-to-text/input.html#transmission)
   *
   [Timeouts](https://cloud.ibm.com/docs/services/speech-to-text/input.html#timeouts)


   ### Audio formats (content types)

    The service accepts audio in the following formats (MIME types).
   * For formats that are labeled **Required**, you must use the `Content-Type`
   header with the request to specify the format of the audio.
   * For all other formats, you can omit the `Content-Type` header or specify
   `application/octet-stream` with the header to have the service automatically
   detect the format of the audio. (With the `curl` command, you can specify either
   `\"Content-Type:\"` or `\"Content-Type: application/octet-stream\"`.)

   Where indicated, the format that you specify must include the sampling rate and
   can optionally include the number of channels and the endianness of the audio.
   * `audio/alaw` (**Required.** Specify the sampling rate (`rate`) of the audio.)
   * `audio/basic` (**Required.** Use only with narrowband models.)
   * `audio/flac`
   * `audio/g729` (Use only with narrowband models.)
   * `audio/l16` (**Required.** Specify the sampling rate (`rate`) and optionally the
   number of channels (`channels`) and endianness (`endianness`) of the audio.)
   * `audio/mp3`
   * `audio/mpeg`
   * `audio/mulaw` (**Required.** Specify the sampling rate (`rate`) of the audio.)
   * `audio/ogg` (The service automatically detects the codec of the input audio.)
   * `audio/ogg;codecs=opus`
   * `audio/ogg;codecs=vorbis`
   * `audio/wav` (Provide audio with a maximum of nine channels.)
   * `audio/webm` (The service automatically detects the codec of the input audio.)
   * `audio/webm;codecs=opus`
   * `audio/webm;codecs=vorbis`

   The sampling rate of the audio must match the sampling rate of the model for the
   recognition request: for broadband models, at least 16 kHz; for narrowband models,
   at least 8 kHz. If the sampling rate of the audio is higher than the minimum
   required rate, the service down-samples the audio to the appropriate rate. If the
   sampling rate of the audio is lower than the minimum required rate, the request
   fails.

    **See also:** [Audio
   formats](https://cloud.ibm.com/docs/services/speech-to-text/audio-formats.html).
 @param audio [String] The audio to transcribe.
 @param model [String] The identifier of the model that is to be used for the recognition request. See
   [Languages and
   models](https://cloud.ibm.com/docs/services/speech-to-text/models.html).
 @param callback_url [String] A URL to which callback notifications are to be sent. The URL must already be
   successfully white-listed by using the **Register a callback** method. You can
   include the same callback URL with any number of job creation requests. Omit the
   parameter to poll the service for job completion and results.

   Use the `user_token` parameter to specify a unique user-specified string with each
   job to differentiate the callback notifications for the jobs.
 @param events [String] If the job includes a callback URL, a comma-separated list of notification events
   to which to subscribe. Valid events are
   * `recognitions.started` generates a callback notification when the service begins
   to process the job.
   * `recognitions.completed` generates a callback notification when the job is
   complete. You must use the **Check a job** method to retrieve the results before
   they time out or are deleted.
   * `recognitions.completed_with_results` generates a callback notification when the
   job is complete. The notification includes the results of the request.
   * `recognitions.failed` generates a callback notification if the service
   experiences an error while processing the job.

   The `recognitions.completed` and `recognitions.completed_with_results` events are
   incompatible. You can specify only of the two events.

   If the job includes a callback URL, omit the parameter to subscribe to the default
   events: `recognitions.started`, `recognitions.completed`, and
   `recognitions.failed`. If the job does not include a callback URL, omit the
   parameter.
 @param user_token [String] If the job includes a callback URL, a user-specified string that the service is to
   include with each callback notification for the job; the token allows the user to
   maintain an internal mapping between jobs and notification events. If the job does
   not include a callback URL, omit the parameter.
 @param results_ttl [Fixnum] The number of minutes for which the results are to be available after the job has
   finished. If not delivered via a callback, the results must be retrieved within
   this time. Omit the parameter to use a time to live of one week. The parameter is
   valid with or without a callback URL.
 @param language_customization_id [String] The customization ID (GUID) of a custom language model that is to be used with the
   recognition request. The base model of the specified custom language model must
   match the model specified with the `model` parameter. You must make the request
   with credentials for the instance of the service that owns the custom model. By
   default, no custom language model is used. See [Custom
   models](https://cloud.ibm.com/docs/services/speech-to-text/input.html#custom-input).


   **Note:** Use this parameter instead of the deprecated `customization_id`
   parameter.
 @param acoustic_customization_id [String] The customization ID (GUID) of a custom acoustic model that is to be used with the
   recognition request. The base model of the specified custom acoustic model must
   match the model specified with the `model` parameter. You must make the request
   with credentials for the instance of the service that owns the custom model. By
   default, no custom acoustic model is used. See [Custom
   models](https://cloud.ibm.com/docs/services/speech-to-text/input.html#custom-input).
 @param base_model_version [String] The version of the specified base model that is to be used with recognition
   request. Multiple versions of a base model can exist when a model is updated for
   internal improvements. The parameter is intended primarily for use with custom
   models that have been upgraded for a new base model. The default value depends on
   whether the parameter is used with or without a custom model. See [Base model
   version](https://cloud.ibm.com/docs/services/speech-to-text/input.html#version).
 @param customization_weight [Float] If you specify the customization ID (GUID) of a custom language model with the
   recognition request, the customization weight tells the service how much weight to
   give to words from the custom language model compared to those from the base model
   for the current request.

   Specify a value between 0.0 and 1.0. Unless a different customization weight was
   specified for the custom model when it was trained, the default value is 0.3. A
   customization weight that you specify overrides a weight that was specified when
   the custom model was trained.

   The default value yields the best performance in general. Assign a higher value if
   your audio makes frequent use of OOV words from the custom model. Use caution when
   setting the weight: a higher value can improve the accuracy of phrases from the
   custom model's domain, but it can negatively affect performance on non-domain
   phrases.

   See [Custom
   models](https://cloud.ibm.com/docs/services/speech-to-text/input.html#custom-input).
 @param inactivity_timeout [Fixnum] The time in seconds after which, if only silence (no speech) is detected in
   streaming audio, the connection is closed with a 400 error. The parameter is
   useful for stopping audio submission from a live microphone when a user simply
   walks away. Use `-1` for infinity. See [Inactivity
   timeout](https://cloud.ibm.com/docs/services/speech-to-text/input.html#timeouts-inactivity).
 @param keywords [Array[String]] An array of keyword strings to spot in the audio. Each keyword string can include
   one or more string tokens. Keywords are spotted only in the final results, not in
   interim hypotheses. If you specify any keywords, you must also specify a keywords
   threshold. You can spot a maximum of 1000 keywords. Omit the parameter or specify
   an empty array if you do not need to spot keywords. See [Keyword
   spotting](https://cloud.ibm.com/docs/services/speech-to-text/output.html#keyword_spotting).
 @param keywords_threshold [Float] A confidence value that is the lower bound for spotting a keyword. A word is
   considered to match a keyword if its confidence is greater than or equal to the
   threshold. Specify a probability between 0.0 and 1.0. If you specify a threshold,
   you must also specify one or more keywords. The service performs no keyword
   spotting if you omit either parameter. See [Keyword
   spotting](https://cloud.ibm.com/docs/services/speech-to-text/output.html#keyword_spotting).
 @param max_alternatives [Fixnum] The maximum number of alternative transcripts that the service is to return. By
   default, the service returns a single transcript. If you specify a value of `0`,
   the service uses the default value, `1`. See [Maximum
   alternatives](https://cloud.ibm.com/docs/services/speech-to-text/output.html#max_alternatives).
 @param word_alternatives_threshold [Float] A confidence value that is the lower bound for identifying a hypothesis as a
   possible word alternative (also known as \"Confusion Networks\"). An alternative
   word is considered if its confidence is greater than or equal to the threshold.
   Specify a probability between 0.0 and 1.0. By default, the service computes no
   alternative words. See [Word
   alternatives](https://cloud.ibm.com/docs/services/speech-to-text/output.html#word_alternatives).
 @param word_confidence [Boolean] If `true`, the service returns a confidence measure in the range of 0.0 to 1.0 for
   each word. By default, the service returns no word confidence scores. See [Word
   confidence](https://cloud.ibm.com/docs/services/speech-to-text/output.html#word_confidence).
 @param timestamps [Boolean] If `true`, the service returns time alignment for each word. By default, no
   timestamps are returned. See [Word
   timestamps](https://cloud.ibm.com/docs/services/speech-to-text/output.html#word_timestamps).
 @param profanity_filter [Boolean] If `true`, the service filters profanity from all output except for keyword
   results by replacing inappropriate words with a series of asterisks. Set the
   parameter to `false` to return results with no censoring. Applies to US English
   transcription only. See [Profanity
   filtering](https://cloud.ibm.com/docs/services/speech-to-text/output.html#profanity_filter).
 @param smart_formatting [Boolean] If `true`, the service converts dates, times, series of digits and numbers, phone
   numbers, currency values, and internet addresses into more readable, conventional
   representations in the final transcript of a recognition request. For US English,
   the service also converts certain keyword strings to punctuation symbols. By
   default, the service performs no smart formatting.

   **Note:** Applies to US English, Japanese, and Spanish transcription only.

   See [Smart
   formatting](https://cloud.ibm.com/docs/services/speech-to-text/output.html#smart_formatting).
 @param speaker_labels [Boolean] If `true`, the response includes labels that identify which words were spoken by
   which participants in a multi-person exchange. By default, the service returns no
   speaker labels. Setting `speaker_labels` to `true` forces the `timestamps`
   parameter to be `true`, regardless of whether you specify `false` for the
   parameter.

   **Note:** Applies to US English, Japanese, and Spanish transcription only. To
   determine whether a language model supports speaker labels, you can also use the
   **Get a model** method and check that the attribute `speaker_labels` is set to
   `true`.

   See [Speaker
   labels](https://cloud.ibm.com/docs/services/speech-to-text/output.html#speaker_labels).
 @param customization_id [String] **Deprecated.** Use the `language_customization_id` parameter to specify the
   customization ID (GUID) of a custom language model that is to be used with the
   recognition request. Do not specify both parameters with a request.
 @param grammar_name [String] The name of a grammar that is to be used with the recognition request. If you
   specify a grammar, you must also use the `language_customization_id` parameter to
   specify the name of the custom language model for which the grammar is defined.
   The service recognizes only strings that are recognized by the specified grammar;
   it does not recognize other custom words from the model's words resource. See
   [Grammars](https://cloud.ibm.com/docs/services/speech-to-text/input.html#grammars-input).
 @param redaction [Boolean] If `true`, the service redacts, or masks, numeric data from final transcripts. The
   feature redacts any number that has three or more consecutive digits by replacing
   each digit with an `X` character. It is intended to redact sensitive numeric data,
   such as credit card numbers. By default, the service performs no redaction.

   When you enable redaction, the service automatically enables smart formatting,
   regardless of whether you explicitly disable that feature. To ensure maximum
   security, the service also disables keyword spotting (ignores the `keywords` and
   `keywords_threshold` parameters) and returns only a single final transcript
   (forces the `max_alternatives` parameter to be `1`).

   **Note:** Applies to US English, Japanese, and Korean transcription only.

   See [Numeric
   redaction](https://cloud.ibm.com/docs/services/speech-to-text/output.html#redaction).
 @param content_type [String] The format (MIME type) of the audio. For more information about specifying an
   audio format, see **Audio formats (content types)** in the method description.
 @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.