docs: def recognize(self,
                    audio,
                    model=None,
                    language_customization_id=None,
                    acoustic_customization_id=None,
                    base_model_version=None,
                    customization_weight=None,
                    inactivity_timeout=None,
                    keywords=None,
                    keywords_threshold=None,
                    max_alternatives=None,
                    word_alternatives_threshold=None,
                    word_confidence=None,
                    timestamps=None,
                    profanity_filter=None,
                    smart_formatting=None,
                    speaker_labels=None,
                    customization_id=None,
                    grammar_name=None,
                    redaction=None,
                    content_type=None,
                    **kwargs):
          """
          Recognize audio.
  
          Sends audio and returns transcription results for a recognition request. You can
          pass a maximum of 100 MB 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:** [Making a basic HTTP
          request](https://cloud.ibm.com/docs/services/speech-to-text/http.html#HTTP-basic).
          ### 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).
          ### Multipart speech recognition
           **Note:** The Watson SDKs do not support multipart speech recognition.
          The HTTP `POST` method of the service also supports multipart speech recognition.
          With multipart requests, you pass all audio data as multipart form data. You
          specify some parameters as request headers and query parameters, but you pass JSON
          metadata as form data to control most aspects of the transcription.
          The multipart approach is intended for use with browsers for which JavaScript is
          disabled or when the parameters used with the request are greater than the 8 KB
          limit imposed by most HTTP servers and proxies. You can encounter this limit, for
          example, if you want to spot a very large number of keywords.
          **See also:** [Making a multipart HTTP
          request](https://cloud.ibm.com/docs/services/speech-to-text/http.html#HTTP-multi).
  
          :param file audio: The audio to transcribe.
          :param str model: 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 str language_customization_id: 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 str acoustic_customization_id: 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 str base_model_version: 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 float customization_weight: 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 int inactivity_timeout: 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 list[str] keywords: 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 float keywords_threshold: 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 int max_alternatives: 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 float word_alternatives_threshold: 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 bool word_confidence: 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 bool timestamps: 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 bool profanity_filter: 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 bool smart_formatting: 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 bool speaker_labels: 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 str customization_id: **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 str grammar_name: 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 bool redaction: 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 str content_type: The format (MIME type) of the audio. For more information
          about specifying an audio format, see **Audio formats (content types)** in the
          method description.
          :param dict headers: A `dict` containing the request headers
          :return: A `DetailedResponse` containing the result, headers and HTTP status code.
          :rtype: DetailedResponse
          """
  
          if audio is None:
              raise ValueError('audio must be provided')
  
          headers = {'Content-Type': content_type}
          if 'headers' in kwargs:
              headers.update(kwargs.get('headers'))
          sdk_headers = get_sdk_headers('speech_to_text', 'V1', 'recognize')
          headers.update(sdk_headers)
  
          params = {
              'model': model,
              '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': self._convert_list(keywords),
              '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
  
          url = '/v1/recognize'
          response = self.request(
              method='POST',
              url=url,
              headers=headers,
              params=params,
              data=data,
              accept_json=True)
          return response