ibm_watson 2.1.1 → 2.2.0

data/lib/ibm_watson/speech_to_text_v1.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# (C) Copyright IBM Corp. 2018, 2020.
+# (C) Copyright IBM Corp. 2018, 2022.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,21 +14,28 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# IBM OpenAPI SDK Code Generator Version: 3.31.0-902c9336-20210504-161156
+# IBM OpenAPI SDK Code Generator Version: 3.38.0-07189efd-20210827-205025
 #
 # The IBM Watson™ Speech to Text service provides APIs that use IBM's
-# speech-recognition capabilities to produce transcripts of spoken audio. The service can
+# speech-recognition capabilities to produce transcripts of spoken audio.  The service can
 # transcribe speech from various languages and audio formats. In addition to basic
 # transcription, the service can produce detailed information about many different aspects
 # of the audio. It returns all JSON response content in the UTF-8 character set.
 #
 # The service supports two types of models: previous-generation models that include the
-# terms `Broadband` and `Narrowband` in their names, and beta next-generation models that
+# terms `Broadband` and `Narrowband` in their names, and next-generation models that
 # include the terms `Multimedia` and `Telephony` in their names. Broadband and multimedia
 # models have minimum sampling rates of 16 kHz. Narrowband and telephony models have
-# minimum sampling rates of 8 kHz. The beta next-generation models currently support fewer
-# languages and features, but they offer high throughput and greater transcription
-# accuracy.
+# minimum sampling rates of 8 kHz. The next-generation models offer high throughput and
+# greater transcription accuracy.
+#
+# Effective 15 March 2022, previous-generation models for all languages other than Arabic
+# and Japanese are deprecated. The deprecated models remain available until 15 September
+# 2022, when they will be removed from the service and the documentation. You must migrate
+# to the equivalent next-generation model by the end of service date. For more
+# information, see [Migrating to next-generation
+# models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-migrate).{:
+# deprecated}
 #
 # For speech recognition, the service supports synchronous and asynchronous HTTP
 # Representational State Transfer (REST) interfaces. It also supports a WebSocket
@@ -43,10 +50,9 @@
 # is a formal language specification that lets you restrict the phrases that the service
 # can recognize.
 #
-# Language model customization and acoustic model customization are generally available
-# for production use with all previous-generation models that are generally available.
-# Grammars are beta functionality for all previous-generation models that support language
-# model customization. Next-generation models do not support customization at this time.
+# Language model customization and grammars are available for most previous- and
+# next-generation models. Acoustic model customization is available for all
+# previous-generation models.
 
 require "concurrent"
 require "erb"
@@ -96,8 +102,8 @@ module IBMWatson
     #   among other things. The ordering of the list of models can change from call to
     #   call; do not rely on an alphabetized or static list of models.
     #
-    #   **See also:** [Listing
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-list).
+    #   **See also:** [Listing all
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-list#models-list-all).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_models
       headers = {
@@ -123,11 +129,11 @@ module IBMWatson
     #   with the service. The information includes the name of the model and its minimum
     #   sampling rate in Hertz, among other things.
     #
-    #   **See also:** [Listing
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-list).
-    # @param model_id [String] The identifier of the model in the form of its name from the output of the **Get a
-    #   model** method. (**Note:** The model `ar-AR_BroadbandModel` is deprecated; use
-    #   `ar-MS_BroadbandModel` instead.).
+    #   **See also:** [Listing a specific
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-list#models-list-specific).
+    # @param model_id [String] The identifier of the model in the form of its name from the output of the [List
+    #   models](#listmodels) method. (**Note:** The model `ar-AR_BroadbandModel` is
+    #   deprecated; use `ar-MS_BroadbandModel` instead.).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def get_model(model_id:)
       raise ArgumentError.new("model_id must be provided") if model_id.nil?
@@ -225,39 +231,38 @@ module IBMWatson
     #
     #   ### Next-generation models
     #
-    #    **Note:** The next-generation language models are beta functionality. They
-    #   support a limited number of languages and features at this time. The supported
-    #   languages, models, and features will increase with future releases.
-    #
-    #   The service supports next-generation `Multimedia` (16 kHz) and `Telephony` (8 kHz)
-    #   models for many languages. Next-generation models have higher throughput than the
-    #   service's previous generation of `Broadband` and `Narrowband` models. When you use
-    #   next-generation models, the service can return transcriptions more quickly and
+    #    The service supports next-generation `Multimedia` (16 kHz) and `Telephony` (8
+    #   kHz) models for many languages. Next-generation models have higher throughput than
+    #   the service's previous generation of `Broadband` and `Narrowband` models. When you
+    #   use next-generation models, the service can return transcriptions more quickly and
     #   also provide noticeably better transcription accuracy.
     #
     #   You specify a next-generation model by using the `model` query parameter, as you
-    #   do a previous-generation model. Next-generation models support the same request
-    #   headers as previous-generation models, but they support only the following
-    #   additional query parameters:
-    #   * `background_audio_suppression`
-    #   * `inactivity_timeout`
-    #   * `profanity_filter`
-    #   * `redaction`
-    #   * `smart_formatting`
-    #   * `speaker_labels`
-    #   * `speech_detector_sensitivity`
-    #   * `timestamps`
+    #   do a previous-generation model. Many next-generation models also support the
+    #   `low_latency` parameter, which is not available with previous-generation models.
+    #   Next-generation models do not support all of the parameters that are available for
+    #   use with previous-generation models.
     #
-    #   Many next-generation models also support the beta `low_latency` parameter, which
-    #   is not available with previous-generation models.
+    #   **Important:** Effective 15 March 2022, previous-generation models for all
+    #   languages other than Arabic and Japanese are deprecated. The deprecated models
+    #   remain available until 15 September 2022, when they will be removed from the
+    #   service and the documentation. You must migrate to the equivalent next-generation
+    #   model by the end of service date. For more information, see [Migrating to
+    #   next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-migrate).
     #
-    #   **See also:** [Next-generation languages and
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng).
+    #
+    #   **See also:**
+    #   * [Next-generation languages and
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng)
+    #   * [Supported features for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng#models-ng-features)
     #
     #
     #   ### Multipart speech recognition
     #
-    #    **Note:** The Watson SDKs do not support multipart speech recognition.
+    #    **Note:** The asynchronous HTTP interface, WebSocket interface, and 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
@@ -277,10 +282,8 @@ module IBMWatson
     #   audio format, see **Audio formats (content types)** in the method description.
     # @param model [String] The identifier of the model that is to be used for the recognition request.
     #   (**Note:** The model `ar-AR_BroadbandModel` is deprecated; use
-    #   `ar-MS_BroadbandModel` instead.) See [Languages and
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models) and
-    #   [Next-generation languages and
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng).
+    #   `ar-MS_BroadbandModel` instead.) See [Using a model for speech
+    #   recognition](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-use).
     # @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
@@ -365,8 +368,10 @@ module IBMWatson
     #   timestamps](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-metadata#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
-    #   and Japanese transcription only. See [Profanity
+    #   parameter to `false` to return results with no censoring.
+    #
+    #   **Note:** The parameter can be used with US English and Japanese transcription
+    #   only. See [Profanity
     #   filtering](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-formatting#profanity-filtering).
     # @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
@@ -374,7 +379,8 @@ module IBMWatson
     #   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.
+    #   **Note:** The parameter can be used with US English, Japanese, and Spanish (all
+    #   dialects) transcription only.
     #
     #   See [Smart
     #   formatting](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-formatting#smart-formatting).
@@ -383,14 +389,14 @@ module IBMWatson
     #   speaker labels. Setting `speaker_labels` to `true` forces the `timestamps`
     #   parameter to be `true`, regardless of whether you specify `false` for the
     #   parameter.
-    #   * For previous-generation models, can be used for US English, Australian English,
-    #   German, Japanese, Korean, and Spanish (both broadband and narrowband models) and
-    #   UK English (narrowband model) transcription only.
-    #   * For next-generation models, can be used for English (Australian, UK, and US),
-    #   German, and Spanish transcription only.
-    #
-    #   Restrictions and limitations apply to the use of speaker labels for both types of
-    #   models. See [Speaker
+    #   * _For previous-generation models,_ the parameter can be used with Australian
+    #   English, US English, German, Japanese, Korean, and Spanish (both broadband and
+    #   narrowband models) and UK English (narrowband model) transcription only.
+    #   * _For next-generation models,_ the parameter can be used with Czech, English
+    #   (Australian, Indian, UK, and US), German, Japanese, Korean, and Spanish
+    #   transcription only.
+    #
+    #   See [Speaker
     #   labels](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-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
@@ -399,8 +405,9 @@ module IBMWatson
     #   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
-    #   [Using a grammar for speech
+    #   it does not recognize other custom words from the model's words resource.
+    #
+    #   See [Using a grammar for speech
     #   recognition](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-grammarUse).
     # @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
@@ -413,7 +420,8 @@ module IBMWatson
     #   `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.
+    #   **Note:** The parameter can be used with US English, Japanese, and Korean
+    #   transcription only.
     #
     #   See [Numeric
     #   redaction](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-formatting#numeric-redaction).
@@ -445,8 +453,11 @@ module IBMWatson
     #   meaningful phrases such as sentences. The service bases its understanding of
     #   semantic features on the base language model that you use with a request. Custom
     #   language models and grammars can also influence how and where the service splits a
-    #   transcript. By default, the service splits transcripts based solely on the pause
-    #   interval.
+    #   transcript.
+    #
+    #   By default, the service splits transcripts based solely on the pause interval. If
+    #   the parameters are used together on the same request, `end_of_phrase_silence_time`
+    #   has precedence over `split_transcript_at_phrase_end`.
     #
     #   See [Split transcript at phrase
     #   end](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-parsing#split-transcript).
@@ -461,8 +472,13 @@ module IBMWatson
     #   * 0.5 (the default) provides a reasonable compromise for the level of sensitivity.
     #   * 1.0 suppresses no audio (speech detection sensitivity is disabled).
     #
-    #   The values increase on a monotonic curve. See [Speech detector
-    #   sensitivity](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-sensitivity).
+    #   The values increase on a monotonic curve.
+    #
+    #   The parameter is supported with all next-generation models and with most
+    #   previous-generation models. See [Speech detector
+    #   sensitivity](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-sensitivity)
+    #   and [Language model
+    #   support](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-support).
     # @param background_audio_suppression [Float] The level to which the service is to suppress background audio based on its volume
     #   to prevent it from being transcribed as speech. Use the parameter to suppress side
     #   conversations or background noise.
@@ -473,8 +489,13 @@ module IBMWatson
     #   * 0.5 provides a reasonable level of audio suppression for general usage.
     #   * 1.0 suppresses all audio (no audio is transcribed).
     #
-    #   The values increase on a monotonic curve. See [Background audio
-    #   suppression](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-suppression).
+    #   The values increase on a monotonic curve.
+    #
+    #   The parameter is supported with all next-generation models and with most
+    #   previous-generation models. See [Background audio
+    #   suppression](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-suppression)
+    #   and [Language model
+    #   support](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-support).
     # @param low_latency [Boolean] If `true` for next-generation `Multimedia` and `Telephony` models that support low
     #   latency, directs the service to produce results even more quickly than it usually
     #   does. Next-generation models produce transcription results faster than
@@ -482,14 +503,11 @@ module IBMWatson
     #   produce results even more quickly, though the results might be less accurate when
     #   the parameter is used.
     #
-    #   **Note:** The parameter is beta functionality. It is not available for
-    #   previous-generation `Broadband` and `Narrowband` models. It is available only for
-    #   some next-generation models.
-    #
-    #   * For a list of next-generation models that support low latency, see [Supported
-    #   language
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng#models-ng-supported)
-    #   for next-generation models.
+    #   The parameter is not available for previous-generation `Broadband` and
+    #   `Narrowband` models. It is available only for some next-generation models. For a
+    #   list of next-generation models that support low latency, see [Supported
+    #   next-generation language
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng#models-ng-supported).
     #   * For more information about the `low_latency` parameter, see [Low
     #   latency](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-interim#low-latency).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
@@ -760,6 +778,7 @@ module IBMWatson
       options.delete_if { |_, v| v.nil? }
       WebSocketClient.new(audio: audio, chunk_data: chunk_data, options: options, recognize_callback: recognize_callback, service_url: service_url, headers: headers, disable_ssl_verification: @disable_ssl_verification)
     end
+
     #########################
     # Asynchronous
     #########################
@@ -783,9 +802,9 @@ module IBMWatson
     #   The service sends only a single `GET` request to the callback URL. If the service
     #   does not receive a reply with a response code of 200 and a body that echoes the
     #   challenge string sent by the service within five seconds, it does not allowlist
-    #   the URL; it instead sends status code 400 in response to the **Register a
-    #   callback** request. If the requested callback URL is already allowlisted, the
-    #   service responds to the initial registration request with response code 200.
+    #   the URL; it instead sends status code 400 in response to the request to register a
+    #   callback. If the requested callback URL is already allowlisted, the service
+    #   responds to the initial registration request with response code 200.
     #
     #   If you specify a user secret with the request, the service uses it as a key to
     #   calculate an HMAC-SHA1 signature of the challenge string in its response to the
@@ -840,9 +859,10 @@ module IBMWatson
     ##
     # @!method unregister_callback(callback_url:)
     # Unregister a callback.
-    # Unregisters a callback URL that was previously allowlisted with a **Register a
-    #   callback** request for use with the asynchronous interface. Once unregistered, the
-    #   URL can no longer be used with asynchronous recognition requests.
+    # Unregisters a callback URL that was previously allowlisted with a [Register a
+    #   callback](#registercallback) request for use with the asynchronous interface. Once
+    #   unregistered, the URL can no longer be used with asynchronous recognition
+    #   requests.
     #
     #   **See also:** [Unregistering a callback
     #   URL](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-async#unregister).
@@ -885,17 +905,17 @@ module IBMWatson
     #   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.
+    #   parameters. You must then use the [Check jobs](#checkjobs) or [Check a
+    #   job](#checkjob) 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.
+    #   HTTPS [Check a job](#checkjob) 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
@@ -975,47 +995,43 @@ module IBMWatson
     #
     #   ### Next-generation models
     #
-    #    **Note:** The next-generation language models are beta functionality. They
-    #   support a limited number of languages and features at this time. The supported
-    #   languages, models, and features will increase with future releases.
-    #
-    #   The service supports next-generation `Multimedia` (16 kHz) and `Telephony` (8 kHz)
-    #   models for many languages. Next-generation models have higher throughput than the
-    #   service's previous generation of `Broadband` and `Narrowband` models. When you use
-    #   next-generation models, the service can return transcriptions more quickly and
+    #    The service supports next-generation `Multimedia` (16 kHz) and `Telephony` (8
+    #   kHz) models for many languages. Next-generation models have higher throughput than
+    #   the service's previous generation of `Broadband` and `Narrowband` models. When you
+    #   use next-generation models, the service can return transcriptions more quickly and
     #   also provide noticeably better transcription accuracy.
     #
     #   You specify a next-generation model by using the `model` query parameter, as you
-    #   do a previous-generation model. Next-generation models support the same request
-    #   headers as previous-generation models, but they support only the following
-    #   additional query parameters:
-    #   * `background_audio_suppression`
-    #   * `inactivity_timeout`
-    #   * `profanity_filter`
-    #   * `redaction`
-    #   * `smart_formatting`
-    #   * `speaker_labels`
-    #   * `speech_detector_sensitivity`
-    #   * `timestamps`
-    #
-    #   Many next-generation models also support the beta `low_latency` parameter, which
-    #   is not available with previous-generation models.
-    #
-    #   **See also:** [Next-generation languages and
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng).
+    #   do a previous-generation model. Many next-generation models also support the
+    #   `low_latency` parameter, which is not available with previous-generation models.
+    #   Next-generation models do not support all of the parameters that are available for
+    #   use with previous-generation models.
+    #
+    #   **Important:** Effective 15 March 2022, previous-generation models for all
+    #   languages other than Arabic and Japanese are deprecated. The deprecated models
+    #   remain available until 15 September 2022, when they will be removed from the
+    #   service and the documentation. You must migrate to the equivalent next-generation
+    #   model by the end of service date. For more information, see  [Migrating to
+    #   next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-migrate).
+    #
+    #
+    #   **See also:**
+    #   * [Next-generation languages and
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng)
+    #   * [Supported features for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng#models-ng-features).
     # @param audio [File] The audio to transcribe.
     # @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.
     # @param model [String] The identifier of the model that is to be used for the recognition request.
     #   (**Note:** The model `ar-AR_BroadbandModel` is deprecated; use
-    #   `ar-MS_BroadbandModel` instead.) See [Languages and
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models) and
-    #   [Next-generation languages and
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng).
+    #   `ar-MS_BroadbandModel` instead.) See [Using a model for speech
+    #   recognition](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-use).
     # @param callback_url [String] A URL to which callback notifications are to be sent. The URL must already be
-    #   successfully allowlisted 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.
+    #   successfully allowlisted by using the [Register a callback](#registercallback)
+    #   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.
@@ -1024,8 +1040,8 @@ module IBMWatson
     #   * `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.
+    #   complete. You must use the [Check a job](#checkjob) 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
@@ -1130,8 +1146,10 @@ module IBMWatson
     #   timestamps](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-metadata#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
-    #   and Japanese transcription only. See [Profanity
+    #   parameter to `false` to return results with no censoring.
+    #
+    #   **Note:** The parameter can be used with US English and Japanese transcription
+    #   only. See [Profanity
     #   filtering](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-formatting#profanity-filtering).
     # @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
@@ -1139,7 +1157,8 @@ module IBMWatson
     #   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.
+    #   **Note:** The parameter can be used with US English, Japanese, and Spanish (all
+    #   dialects) transcription only.
     #
     #   See [Smart
     #   formatting](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-formatting#smart-formatting).
@@ -1148,14 +1167,14 @@ module IBMWatson
     #   speaker labels. Setting `speaker_labels` to `true` forces the `timestamps`
     #   parameter to be `true`, regardless of whether you specify `false` for the
     #   parameter.
-    #   * For previous-generation models, can be used for US English, Australian English,
-    #   German, Japanese, Korean, and Spanish (both broadband and narrowband models) and
-    #   UK English (narrowband model) transcription only.
-    #   * For next-generation models, can be used for English (Australian, UK, and US),
-    #   German, and Spanish transcription only.
-    #
-    #   Restrictions and limitations apply to the use of speaker labels for both types of
-    #   models. See [Speaker
+    #   * _For previous-generation models,_ the parameter can be used with Australian
+    #   English, US English, German, Japanese, Korean, and Spanish (both broadband and
+    #   narrowband models) and UK English (narrowband model) transcription only.
+    #   * _For next-generation models,_ the parameter can be used with Czech, English
+    #   (Australian, Indian, UK, and US), German, Japanese, Korean, and Spanish
+    #   transcription only.
+    #
+    #   See [Speaker
     #   labels](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-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
@@ -1164,8 +1183,9 @@ module IBMWatson
     #   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
-    #   [Using a grammar for speech
+    #   it does not recognize other custom words from the model's words resource.
+    #
+    #   See [Using a grammar for speech
     #   recognition](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-grammarUse).
     # @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
@@ -1178,7 +1198,8 @@ module IBMWatson
     #   `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.
+    #   **Note:** The parameter can be used with US English, Japanese, and Korean
+    #   transcription only.
     #
     #   See [Numeric
     #   redaction](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-formatting#numeric-redaction).
@@ -1232,8 +1253,11 @@ module IBMWatson
     #   meaningful phrases such as sentences. The service bases its understanding of
     #   semantic features on the base language model that you use with a request. Custom
     #   language models and grammars can also influence how and where the service splits a
-    #   transcript. By default, the service splits transcripts based solely on the pause
-    #   interval.
+    #   transcript.
+    #
+    #   By default, the service splits transcripts based solely on the pause interval. If
+    #   the parameters are used together on the same request, `end_of_phrase_silence_time`
+    #   has precedence over `split_transcript_at_phrase_end`.
     #
     #   See [Split transcript at phrase
     #   end](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-parsing#split-transcript).
@@ -1248,8 +1272,13 @@ module IBMWatson
     #   * 0.5 (the default) provides a reasonable compromise for the level of sensitivity.
     #   * 1.0 suppresses no audio (speech detection sensitivity is disabled).
     #
-    #   The values increase on a monotonic curve. See [Speech detector
-    #   sensitivity](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-sensitivity).
+    #   The values increase on a monotonic curve.
+    #
+    #   The parameter is supported with all next-generation models and with most
+    #   previous-generation models. See [Speech detector
+    #   sensitivity](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-sensitivity)
+    #   and [Language model
+    #   support](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-support).
     # @param background_audio_suppression [Float] The level to which the service is to suppress background audio based on its volume
     #   to prevent it from being transcribed as speech. Use the parameter to suppress side
     #   conversations or background noise.
@@ -1260,8 +1289,13 @@ module IBMWatson
     #   * 0.5 provides a reasonable level of audio suppression for general usage.
     #   * 1.0 suppresses all audio (no audio is transcribed).
     #
-    #   The values increase on a monotonic curve. See [Background audio
-    #   suppression](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-suppression).
+    #   The values increase on a monotonic curve.
+    #
+    #   The parameter is supported with all next-generation models and with most
+    #   previous-generation models. See [Background audio
+    #   suppression](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-parameters-suppression)
+    #   and [Language model
+    #   support](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-detection#detection-support).
     # @param low_latency [Boolean] If `true` for next-generation `Multimedia` and `Telephony` models that support low
     #   latency, directs the service to produce results even more quickly than it usually
     #   does. Next-generation models produce transcription results faster than
@@ -1269,14 +1303,11 @@ module IBMWatson
     #   produce results even more quickly, though the results might be less accurate when
     #   the parameter is used.
     #
-    #   **Note:** The parameter is beta functionality. It is not available for
-    #   previous-generation `Broadband` and `Narrowband` models. It is available only for
-    #   some next-generation models.
-    #
-    #   * For a list of next-generation models that support low latency, see [Supported
-    #   language
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng#models-ng-supported)
-    #   for next-generation models.
+    #   The parameter is not available for previous-generation `Broadband` and
+    #   `Narrowband` models. It is available only for some next-generation models. For a
+    #   list of next-generation models that support low latency, see [Supported
+    #   next-generation language
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng#models-ng-supported).
     #   * For more information about the `low_latency` parameter, see [Low
     #   latency](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-interim#low-latency).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
@@ -1345,10 +1376,10 @@ module IBMWatson
     #   credentials with which it is called. The method also returns the creation and
     #   update times of each job, and, if a job was created with a callback URL and a user
     #   token, the user token for the job. To obtain the results for a job whose status is
-    #   `completed` or not one of the latest 100 outstanding jobs, use the **Check a job**
-    #   method. A job and its results remain available until you delete them with the
-    #   **Delete a job** method or until the job's time to live expires, whichever comes
-    #   first.
+    #   `completed` or not one of the latest 100 outstanding jobs, use the [Check a
+    #   job[(#checkjob) method. A job and its results remain available until you delete
+    #   them with the [Delete a job](#deletejob) method or until the job's time to live
+    #   expires, whichever comes first.
     #
     #   **See also:** [Checking the status of the latest
     #   jobs](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-async#jobs).
@@ -1382,8 +1413,8 @@ module IBMWatson
     #   You can use the method to retrieve the results of any job, regardless of whether
     #   it was submitted with a callback URL and the `recognitions.completed_with_results`
     #   event, and you can retrieve the results multiple times for as long as they remain
-    #   available. Use the **Check jobs** method to request information about the most
-    #   recent jobs associated with the calling credentials.
+    #   available. Use the [Check jobs](#checkjobs) method to request information about
+    #   the most recent jobs associated with the calling credentials.
     #
     #   **See also:** [Checking the status and retrieving the results of a
     #   job](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-async#job).
@@ -1460,8 +1491,20 @@ module IBMWatson
     #   do not lose any models, but you cannot create any more until your model count is
     #   below the limit.
     #
-    #   **See also:** [Create a custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#createModel-language).
+    #   **Important:** Effective 15 March 2022, previous-generation models for all
+    #   languages other than Arabic and Japanese are deprecated. The deprecated models
+    #   remain available until 15 September 2022, when they will be removed from the
+    #   service and the documentation. You must migrate to the equivalent next-generation
+    #   model by the end of service date. For more information, see [Migrating to
+    #   next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-migrate).
+    #
+    #
+    #   **See also:**
+    #   * [Create a custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#createModel-language)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param name [String] A user-defined name for the new custom language model. Use a name that is unique
     #   among all custom language models that you own. Use a localized name that matches
     #   the language of the custom model. Use a name that describes the domain of the
@@ -1471,28 +1514,26 @@ module IBMWatson
     #   customizes.
     #
     #   To determine whether a base model supports language model customization, use the
-    #   **Get a model** method and check that the attribute `custom_language_model` is set
-    #   to `true`. You can also refer to [Language support for
-    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-customization#languageSupport).
+    #   [Get a model](#getmodel) method and check that the attribute
+    #   `custom_language_model` is set to `true`. You can also refer to [Language support
+    #   for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param dialect [String] The dialect of the specified language that is to be used with the custom language
-    #   model. For most languages, the dialect matches the language of the base model by
-    #   default. For example, `en-US` is used for either of the US English language
-    #   models.
-    #
-    #   For a Spanish language, the service creates a custom language model that is suited
-    #   for speech in one of the following dialects:
+    #   model. _For all languages, it is always safe to omit this field._ The service
+    #   automatically uses the language identifier from the name of the base model. For
+    #   example, the service automatically uses `en-US` for all US English models.
+    #
+    #   If you specify the `dialect` for a new custom model, follow these guidelines. _For
+    #   non-Spanish previous-generation models and for next-generation models,_ you must
+    #   specify a value that matches the five-character language identifier from the name
+    #   of the base model. _For Spanish previous-generation models,_ you must specify one
+    #   of the following values:
     #   * `es-ES` for Castilian Spanish (`es-ES` models)
     #   * `es-LA` for Latin American Spanish (`es-AR`, `es-CL`, `es-CO`, and `es-PE`
     #   models)
     #   * `es-US` for Mexican (North American) Spanish (`es-MX` models)
     #
-    #   The parameter is meaningful only for Spanish models, for which you can always
-    #   safely omit the parameter to have the service create the correct mapping.
-    #
-    #   If you specify the `dialect` parameter for non-Spanish language models, its value
-    #   must match the language of the base model. If you specify the `dialect` for
-    #   Spanish language models, its value must match one of the defined mappings as
-    #   indicated (`es-ES`, `es-LA`, or `es-MX`). All dialect values are case-insensitive.
+    #   All values that you pass for the `dialect` field are case-insensitive.
     # @param description [String] A description of the new custom language model. Use a localized description that
     #   matches the language of the custom model.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
@@ -1534,16 +1575,21 @@ module IBMWatson
     #   all languages. You must use credentials for the instance of the service that owns
     #   a model to list information about it.
     #
-    #   **See also:** [Listing custom language
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#listModels-language).
+    #   **See also:**
+    #   * [Listing custom language
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#listModels-language)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param language [String] The identifier of the language for which custom language or custom acoustic models
-    #   are to be returned. Omit the parameter to see all custom language or custom
-    #   acoustic models that are owned by the requesting credentials. (**Note:** The
-    #   identifier `ar-AR` is deprecated; use `ar-MS` instead.)
+    #   are to be returned. Specify the five-character language identifier; for example,
+    #   specify `en-US` to see all custom language or custom acoustic models that are
+    #   based on US English models. Omit the parameter to see all custom language or
+    #   custom acoustic models that are owned by the requesting credentials. (**Note:**
+    #   The identifier `ar-AR` is deprecated; use `ar-MS` instead.)
     #
     #   To determine the languages for which customization is available, see [Language
     #   support for
-    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-customization#languageSupport).
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_language_models(language: nil)
       headers = {
@@ -1573,8 +1619,11 @@ module IBMWatson
     # Gets information about a specified custom language model. You must use credentials
     #   for the instance of the service that owns a model to list information about it.
     #
-    #   **See also:** [Listing custom language
-    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#listModels-language).
+    #   **See also:**
+    #   * [Listing custom language
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#listModels-language)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -1606,8 +1655,11 @@ module IBMWatson
     #   being processed. You must use credentials for the instance of the service that
     #   owns a model to delete it.
     #
-    #   **See also:** [Deleting a custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#deleteModel-language).
+    #   **See also:**
+    #   * [Deleting a custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#deleteModel-language)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -1647,15 +1699,19 @@ module IBMWatson
     #   the current load on the service. The method returns an HTTP 200 response code to
     #   indicate that the training process has begun.
     #
-    #   You can monitor the status of the training by using the **Get a custom language
-    #   model** method to poll the model's status. Use a loop to check the status every 10
-    #   seconds. The method returns a `LanguageModel` object that includes `status` and
-    #   `progress` fields. A status of `available` means that the custom model is trained
-    #   and ready to use. The service cannot accept subsequent training requests or
-    #   requests to add new resources until the existing request completes.
+    #   You can monitor the status of the training by using the [Get a custom language
+    #   model](#getlanguagemodel) method to poll the model's status. Use a loop to check
+    #   the status every 10 seconds. The method returns a `LanguageModel` object that
+    #   includes `status` and `progress` fields. A status of `available` means that the
+    #   custom model is trained and ready to use. The service cannot accept subsequent
+    #   training requests or requests to add new resources until the existing request
+    #   completes.
     #
-    #   **See also:** [Train the custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#trainModel-language).
+    #   **See also:**
+    #   * [Train the custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#trainModel-language)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support)
     #
     #
     #   ### Training failures
@@ -1672,14 +1728,18 @@ module IBMWatson
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
-    # @param word_type_to_add [String] The type of words from the custom language model's words resource on which to
-    #   train the model:
+    # @param word_type_to_add [String] _For custom models that are based on previous-generation models_, the type of
+    #   words from the custom language model's words resource on which to train the model:
     #   * `all` (the default) trains the model on all new words, regardless of whether
     #   they were extracted from corpora or grammars or were added or modified by the
     #   user.
-    #   * `user` trains the model only on new words that were added or modified by the
+    #   * `user` trains the model only on custom words that were added or modified by the
     #   user directly. The model is not trained on new words extracted from corpora or
     #   grammars.
+    #
+    #   _For custom models that are based on next-generation models_, the service ignores
+    #   the parameter. The words resource contains only custom words that the user adds or
+    #   modifies directly, so the parameter is unnecessary.
     # @param customization_weight [Float] Specifies a customization weight for the custom language model. 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 speech recognition. Specify a
@@ -1733,8 +1793,11 @@ module IBMWatson
     #   must use credentials for the instance of the service that owns a model to reset
     #   it.
     #
-    #   **See also:** [Resetting a custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#resetModel-language).
+    #   **See also:**
+    #   * [Resetting a custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#resetModel-language)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -1770,15 +1833,20 @@ module IBMWatson
     #
     #   The method returns an HTTP 200 response code to indicate that the upgrade process
     #   has begun successfully. You can monitor the status of the upgrade by using the
-    #   **Get a custom language model** method to poll the model's status. The method
-    #   returns a `LanguageModel` object that includes `status` and `progress` fields. Use
-    #   a loop to check the status every 10 seconds. While it is being upgraded, the
-    #   custom model has the status `upgrading`. When the upgrade is complete, the model
-    #   resumes the status that it had prior to upgrade. The service cannot accept
-    #   subsequent requests for the model until the upgrade completes.
-    #
-    #   **See also:** [Upgrading a custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade#custom-upgrade-language).
+    #   [Get a custom language model](#getlanguagemodel) method to poll the model's
+    #   status. The method returns a `LanguageModel` object that includes `status` and
+    #   `progress` fields. Use a loop to check the status every 10 seconds.
+    #
+    #   While it is being upgraded, the custom model has the status `upgrading`. When the
+    #   upgrade is complete, the model resumes the status that it had prior to upgrade.
+    #   The service cannot accept subsequent requests for the model until the upgrade
+    #   completes.
+    #
+    #   **See also:**
+    #   * [Upgrading a custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade#custom-upgrade-language)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -1809,9 +1877,10 @@ module IBMWatson
     # @!method list_corpora(customization_id:)
     # List corpora.
     # Lists information about all corpora from a custom language model. The information
-    #   includes the total number of words and out-of-vocabulary (OOV) words, name, and
-    #   status of each corpus. You must use credentials for the instance of the service
-    #   that owns a model to list its corpora.
+    #   includes the name, status, and total number of words for each corpus. _For custom
+    #   models that are based on previous-generation models_, it also includes the number
+    #   of out-of-vocabulary (OOV) words from the corpus. You must use credentials for the
+    #   instance of the service that owns a model to list its corpora.
     #
     #   **See also:** [Listing corpora for a custom language
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageCorpora#listCorpora).
@@ -1845,51 +1914,60 @@ module IBMWatson
     #   Use multiple requests to submit multiple corpus text files. You must use
     #   credentials for the instance of the service that owns a model to add a corpus to
     #   it. Adding a corpus does not affect the custom language model until you train the
-    #   model for the new data by using the **Train a custom language model** method.
+    #   model for the new data by using the [Train a custom language
+    #   model](#trainlanguagemodel) method.
     #
     #   Submit a plain text file that contains sample sentences from the domain of
-    #   interest to enable the service to extract words in context. The more sentences you
-    #   add that represent the context in which speakers use words from the domain, the
-    #   better the service's recognition accuracy.
+    #   interest to enable the service to parse the words in context. The more sentences
+    #   you add that represent the context in which speakers use words from the domain,
+    #   the better the service's recognition accuracy.
     #
     #   The call returns an HTTP 201 response code if the corpus is valid. The service
-    #   then asynchronously processes the contents of the corpus and automatically
-    #   extracts new words that it finds. This operation can take on the order of minutes
-    #   to complete depending on the total number of words and the number of new words in
-    #   the corpus, as well as the current load on the service. You cannot submit requests
-    #   to add additional resources to the custom model or to train the model until the
-    #   service's analysis of the corpus for the current request completes. Use the **List
-    #   a corpus** method to check the status of the analysis.
-    #
-    #   The service auto-populates the model's words resource with words from the corpus
-    #   that are not found in its base vocabulary. These words are referred to as
-    #   out-of-vocabulary (OOV) words. After adding a corpus, you must validate the words
-    #   resource to ensure that each OOV word's definition is complete and valid. You can
-    #   use the **List custom words** method to examine the words resource. You can use
-    #   other words method to eliminate typos and modify how words are pronounced as
-    #   needed.
+    #   then asynchronously processes and automatically extracts data from the contents of
+    #   the corpus. This operation can take on the order of minutes to complete depending
+    #   on the current load on the service, the total number of words in the corpus, and,
+    #   _for custom models that are based on previous-generation models_, the number of
+    #   new (out-of-vocabulary) words in the corpus. You cannot submit requests to add
+    #   additional resources to the custom model or to train the model until the service's
+    #   analysis of the corpus for the current request completes. Use the [Get a
+    #   corpus](#getcorpus) method to check the status of the analysis.
+    #
+    #   _For custom models that are based on previous-generation models_, the service
+    #   auto-populates the model's words resource with words from the corpus that are not
+    #   found in its base vocabulary. These words are referred to as out-of-vocabulary
+    #   (OOV) words. After adding a corpus, you must validate the words resource to ensure
+    #   that each OOV word's definition is complete and valid. You can use the [List
+    #   custom words](#listwords) method to examine the words resource. You can use other
+    #   words method to eliminate typos and modify how words are pronounced as needed.
     #
     #   To add a corpus file that has the same name as an existing corpus, set the
     #   `allow_overwrite` parameter to `true`; otherwise, the request fails. Overwriting
     #   an existing corpus causes the service to process the corpus text file and extract
-    #   OOV words anew. Before doing so, it removes any OOV words associated with the
-    #   existing corpus from the model's words resource unless they were also added by
-    #   another corpus or grammar, or they have been modified in some way with the **Add
-    #   custom words** or **Add a custom word** method.
+    #   its data anew. _For a custom model that is based on a previous-generation model_,
+    #   the service first removes any OOV words that are associated with the existing
+    #   corpus from the model's words resource unless they were also added by another
+    #   corpus or grammar, or they have been modified in some way with the [Add custom
+    #   words](#addwords) or [Add a custom word](#addword) method.
     #
     #   The service limits the overall amount of data that you can add to a custom model
-    #   to a maximum of 10 million total words from all sources combined. Also, you can
-    #   add no more than 90 thousand custom (OOV) words to a model. This includes words
-    #   that the service extracts from corpora and grammars, and words that you add
-    #   directly.
+    #   to a maximum of 10 million total words from all sources combined. _For a custom
+    #   model that is based on a previous-generation model_, you can add no more than 90
+    #   thousand custom (OOV) words to a model. This includes words that the service
+    #   extracts from corpora and grammars, and words that you add directly.
     #
     #   **See also:**
     #   * [Add a corpus to the custom language
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#addCorpus)
-    #   * [Working with
-    #   corpora](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#workingCorpora)
-    #   * [Validating a words
-    #   resource](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel).
+    #   * [Working with corpora for previous-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#workingCorpora)
+    #   * [Working with corpora for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords-ng#workingCorpora-ng)
+    #
+    #   * [Validating a words resource for previous-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel)
+    #
+    #   * [Validating a words resource for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords-ng#validateModel-ng).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -1912,10 +1990,10 @@ module IBMWatson
     #   in UTF-8 if it contains non-ASCII characters; the service assumes UTF-8 encoding
     #   if it encounters non-ASCII characters.
     #
-    #   Make sure that you know the character encoding of the file. You must use that
+    #   Make sure that you know the character encoding of the file. You must use that same
     #   encoding when working with the words in the custom language model. For more
-    #   information, see [Character
-    #   encoding](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#charEncoding).
+    #   information, see [Character encoding for custom
+    #   words](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageWords#charEncoding).
     #
     #
     #   With the `curl` command, use the `--data-binary` option to upload the file for the
@@ -1964,9 +2042,10 @@ module IBMWatson
     # @!method get_corpus(customization_id:, corpus_name:)
     # Get a corpus.
     # Gets information about a corpus from a custom language model. The information
-    #   includes the total number of words and out-of-vocabulary (OOV) words, name, and
-    #   status of the corpus. You must use credentials for the instance of the service
-    #   that owns a model to list its corpora.
+    #   includes the name, status, and total number of words for the corpus. _For custom
+    #   models that are based on previous-generation models_, it also includes the number
+    #   of out-of-vocabulary (OOV) words from the corpus. You must use credentials for the
+    #   instance of the service that owns a model to list its corpora.
     #
     #   **See also:** [Listing corpora for a custom language
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageCorpora#listCorpora).
@@ -1999,14 +2078,18 @@ module IBMWatson
     ##
     # @!method delete_corpus(customization_id:, corpus_name:)
     # Delete a corpus.
-    # Deletes an existing corpus from a custom language model. The service removes any
-    #   out-of-vocabulary (OOV) words that are associated with the corpus from the custom
-    #   model's words resource unless they were also added by another corpus or grammar,
-    #   or they were modified in some way with the **Add custom words** or **Add a custom
-    #   word** method. Removing a corpus does not affect the custom model until you train
-    #   the model with the **Train a custom language model** method. You must use
-    #   credentials for the instance of the service that owns a model to delete its
-    #   corpora.
+    # Deletes an existing corpus from a custom language model. Removing a corpus does
+    #   not affect the custom model until you train the model with the [Train a custom
+    #   language model](#trainlanguagemodel) method. You must use credentials for the
+    #   instance of the service that owns a model to delete its corpora.
+    #
+    #   _For custom models that are based on previous-generation models_, the service
+    #   removes any out-of-vocabulary (OOV) words that are associated with the corpus from
+    #   the custom model's words resource unless they were also added by another corpus or
+    #   grammar, or they were modified in some way with the [Add custom words](#addwords)
+    #   or [Add a custom word](#addword) method.
+    #
+    #
     #
     #   **See also:** [Deleting a corpus from a custom language
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageCorpora#deleteCorpus).
@@ -2044,10 +2127,11 @@ module IBMWatson
     # List custom words.
     # Lists information about custom words from a custom language model. You can list
     #   all words from the custom model's words resource, only custom words that were
-    #   added or modified by the user, or only out-of-vocabulary (OOV) words that were
-    #   extracted from corpora or are recognized by grammars. You can also indicate the
-    #   order in which the service is to return words; by default, the service lists words
-    #   in ascending alphabetical order. You must use credentials for the instance of the
+    #   added or modified by the user, or, _for a custom model that is based on a
+    #   previous-generation model_, only out-of-vocabulary (OOV) words that were extracted
+    #   from corpora or are recognized by grammars. You can also indicate the order in
+    #   which the service is to return words; by default, the service lists words in
+    #   ascending alphabetical order. You must use credentials for the instance of the
     #   service that owns a model to list information about its words.
     #
     #   **See also:** [Listing words from a custom language
@@ -2060,6 +2144,10 @@ module IBMWatson
     #   * `user` shows only custom words that were added or modified by the user directly.
     #   * `corpora` shows only OOV that were extracted from corpora.
     #   * `grammars` shows only OOV words that are recognized by grammars.
+    #
+    #   _For a custom model that is based on a next-generation model_, only `all` and
+    #   `user` apply. Both options return the same results. Words from other sources are
+    #   not added to custom models that are based on next-generation models.
     # @param sort [String] Indicates the order in which the words are to be listed, `alphabetical` or by
     #   `count`. You can prepend an optional `+` or `-` to an argument to indicate whether
     #   the results are to be sorted in ascending or descending order. By default, words
@@ -2096,10 +2184,14 @@ module IBMWatson
     ##
     # @!method add_words(customization_id:, words:)
     # Add custom words.
-    # Adds one or more custom words to a custom language model. The service populates
+    # Adds one or more custom words to a custom language model. You can use this method
+    #   to add words or to modify existing words in a custom model's words resource. _For
+    #   custom models that are based on previous-generation models_, the service populates
     #   the words resource for a custom model with out-of-vocabulary (OOV) words from each
-    #   corpus or grammar that is added to the model. You can use this method to add
-    #   additional words or to modify existing words in the words resource. The words
+    #   corpus or grammar that is added to the model. You can use this method to modify
+    #   OOV words in the model's words resource.
+    #
+    #   _For a custom model that is based on a previous-generation model_, the words
     #   resource for a model can contain a maximum of 90 thousand custom (OOV) words. This
     #   includes words that the service extracts from corpora and grammars and words that
     #   you add directly.
@@ -2107,25 +2199,26 @@ module IBMWatson
     #   You must use credentials for the instance of the service that owns a model to add
     #   or modify custom words for the model. Adding or modifying custom words does not
     #   affect the custom model until you train the model for the new data by using the
-    #   **Train a custom language model** method.
+    #   [Train a custom language model](#trainlanguagemodel) method.
     #
     #   You add custom words by providing a `CustomWords` object, which is an array of
-    #   `CustomWord` objects, one per word. You must use the object's `word` parameter to
-    #   identify the word that is to be added. You can also provide one or both of the
-    #   optional `sounds_like` and `display_as` fields for each word.
-    #   * The `sounds_like` field provides an array of one or more pronunciations for the
-    #   word. Use the parameter to specify how the word can be pronounced by users. Use
-    #   the parameter for words that are difficult to pronounce, foreign words, acronyms,
-    #   and so on. For example, you might specify that the word `IEEE` can sound like `i
-    #   triple e`. You can specify a maximum of five sounds-like pronunciations for a
-    #   word. If you omit the `sounds_like` field, the service attempts to set the field
-    #   to its pronunciation of the word. It cannot generate a pronunciation for all
-    #   words, so you must review the word's definition to ensure that it is complete and
-    #   valid.
+    #   `CustomWord` objects, one per word. Use the object's `word` parameter to identify
+    #   the word that is to be added. You can also provide one or both of the optional
+    #   `display_as` or `sounds_like` fields for each word.
     #   * The `display_as` field provides a different way of spelling the word in a
     #   transcript. Use the parameter when you want the word to appear different from its
     #   usual representation or from its spelling in training data. For example, you might
-    #   indicate that the word `IBM(trademark)` is to be displayed as `IBM™`.
+    #   indicate that the word `IBM` is to be displayed as `IBM™`.
+    #   * The `sounds_like` field, _which can be used only with a custom model that is
+    #   based on a previous-generation model_, provides an array of one or more
+    #   pronunciations for the word. Use the parameter to specify how the word can be
+    #   pronounced by users. Use the parameter for words that are difficult to pronounce,
+    #   foreign words, acronyms, and so on. For example, you might specify that the word
+    #   `IEEE` can sound like `i triple e`. You can specify a maximum of five sounds-like
+    #   pronunciations for a word. If you omit the `sounds_like` field, the service
+    #   attempts to set the field to its pronunciation of the word. It cannot generate a
+    #   pronunciation for all words, so you must review the word's definition to ensure
+    #   that it is complete and valid.
     #
     #   If you add a custom word that already exists in the words resource for the custom
     #   model, the new definition overwrites the existing data for the word. If the
@@ -2137,26 +2230,30 @@ module IBMWatson
     #   time that it takes for the analysis to complete depends on the number of new words
     #   that you add but is generally faster than adding a corpus or grammar.
     #
-    #   You can monitor the status of the request by using the **List a custom language
-    #   model** method to poll the model's status. Use a loop to check the status every 10
-    #   seconds. The method returns a `Customization` object that includes a `status`
-    #   field. A status of `ready` means that the words have been added to the custom
-    #   model. The service cannot accept requests to add new data or to train the model
-    #   until the existing request completes.
-    #
-    #   You can use the **List custom words** or **List a custom word** method to review
-    #   the words that you add. Words with an invalid `sounds_like` field include an
-    #   `error` field that describes the problem. You can use other words-related methods
-    #   to correct errors, eliminate typos, and modify how words are pronounced as needed.
+    #   You can monitor the status of the request by using the [Get a custom language
+    #   model](#getlanguagemodel) method to poll the model's status. Use a loop to check
+    #   the status every 10 seconds. The method returns a `Customization` object that
+    #   includes a `status` field. A status of `ready` means that the words have been
+    #   added to the custom model. The service cannot accept requests to add new data or
+    #   to train the model until the existing request completes.
     #
+    #   You can use the [List custom words](#listwords) or [Get a custom word](#getword)
+    #   method to review the words that you add. Words with an invalid `sounds_like` field
+    #   include an `error` field that describes the problem. You can use other
+    #   words-related methods to correct errors, eliminate typos, and modify how words are
+    #   pronounced as needed.
     #
     #   **See also:**
     #   * [Add words to the custom language
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#addWords)
-    #   * [Working with custom
-    #   words](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#workingWords)
-    #   * [Validating a words
-    #   resource](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel).
+    #   * [Working with custom words for previous-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#workingWords)
+    #   * [Working with custom words for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords-ng#workingWords-ng)
+    #   * [Validating a words resource for previous-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel)
+    #   * [Validating a words resource for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords-ng#validateModel-ng).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -2192,47 +2289,57 @@ module IBMWatson
     ##
     # @!method add_word(customization_id:, word_name:, word: nil, sounds_like: nil, display_as: nil)
     # Add a custom word.
-    # Adds a custom word to a custom language model. The service populates the words
-    #   resource for a custom model with out-of-vocabulary (OOV) words from each corpus or
-    #   grammar that is added to the model. You can use this method to add a word or to
-    #   modify an existing word in the words resource. The words resource for a model can
-    #   contain a maximum of 90 thousand custom (OOV) words. This includes words that the
-    #   service extracts from corpora and grammars and words that you add directly.
+    # Adds a custom word to a custom language model. You can use this method to add a
+    #   word or to modify an existing word in the words resource. _For custom models that
+    #   are based on previous-generation models_, the service populates the words resource
+    #   for a custom model with out-of-vocabulary (OOV) words from each corpus or grammar
+    #   that is added to the model. You can use this method to modify OOV words in the
+    #   model's words resource.
+    #
+    #   _For a custom model that is based on a previous-generation models_, the words
+    #   resource for a model can contain a maximum of 90 thousand custom (OOV) words. This
+    #   includes words that the service extracts from corpora and grammars and words that
+    #   you add directly.
     #
     #   You must use credentials for the instance of the service that owns a model to add
     #   or modify a custom word for the model. Adding or modifying a custom word does not
     #   affect the custom model until you train the model for the new data by using the
-    #   **Train a custom language model** method.
+    #   [Train a custom language model](#trainlanguagemodel) method.
     #
     #   Use the `word_name` parameter to specify the custom word that is to be added or
     #   modified. Use the `CustomWord` object to provide one or both of the optional
-    #   `sounds_like` and `display_as` fields for the word.
-    #   * The `sounds_like` field provides an array of one or more pronunciations for the
-    #   word. Use the parameter to specify how the word can be pronounced by users. Use
-    #   the parameter for words that are difficult to pronounce, foreign words, acronyms,
-    #   and so on. For example, you might specify that the word `IEEE` can sound like `i
-    #   triple e`. You can specify a maximum of five sounds-like pronunciations for a
-    #   word. If you omit the `sounds_like` field, the service attempts to set the field
-    #   to its pronunciation of the word. It cannot generate a pronunciation for all
-    #   words, so you must review the word's definition to ensure that it is complete and
-    #   valid.
+    #   `display_as` or `sounds_like` fields for the word.
     #   * The `display_as` field provides a different way of spelling the word in a
     #   transcript. Use the parameter when you want the word to appear different from its
     #   usual representation or from its spelling in training data. For example, you might
-    #   indicate that the word `IBM(trademark)` is to be displayed as `IBM™`.
+    #   indicate that the word `IBM` is to be displayed as `IBM™`.
+    #   * The `sounds_like` field, _which can be used only with a custom model that is
+    #   based on a previous-generation model_, provides an array of one or more
+    #   pronunciations for the word. Use the parameter to specify how the word can be
+    #   pronounced by users. Use the parameter for words that are difficult to pronounce,
+    #   foreign words, acronyms, and so on. For example, you might specify that the word
+    #   `IEEE` can sound like `i triple e`. You can specify a maximum of five sounds-like
+    #   pronunciations for a word. If you omit the `sounds_like` field, the service
+    #   attempts to set the field to its pronunciation of the word. It cannot generate a
+    #   pronunciation for all words, so you must review the word's definition to ensure
+    #   that it is complete and valid.
     #
     #   If you add a custom word that already exists in the words resource for the custom
     #   model, the new definition overwrites the existing data for the word. If the
     #   service encounters an error, it does not add the word to the words resource. Use
-    #   the **List a custom word** method to review the word that you add.
+    #   the [Get a custom word](#getword) method to review the word that you add.
     #
     #   **See also:**
     #   * [Add words to the custom language
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#addWords)
-    #   * [Working with custom
-    #   words](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#workingWords)
-    #   * [Validating a words
-    #   resource](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel).
+    #   * [Working with custom words for previous-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#workingWords)
+    #   * [Working with custom words for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords-ng#workingWords-ng)
+    #   * [Validating a words resource for previous-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel)
+    #   * [Validating a words resource for next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords-ng#validateModel-ng).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -2241,14 +2348,16 @@ module IBMWatson
     #   the tokens of compound words. URL-encode the word if it includes non-ASCII
     #   characters. For more information, see [Character
     #   encoding](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#charEncoding).
-    # @param word [String] For the **Add custom words** method, you must specify the custom word that is to
-    #   be added to or updated in the custom model. Do not include spaces in the word. Use
-    #   a `-` (dash) or `_` (underscore) to connect the tokens of compound words.
-    #
-    #   Omit this parameter for the **Add a custom word** method.
-    # @param sounds_like [Array[String]] An array of sounds-like pronunciations for the custom word. Specify how words that
-    #   are difficult to pronounce, foreign words, acronyms, and so on can be pronounced
-    #   by users.
+    # @param word [String] For the [Add custom words](#addwords) method, you must specify the custom word
+    #   that is to be added to or updated in the custom model. Do not include spaces in
+    #   the word. Use a `-` (dash) or `_` (underscore) to connect the tokens of compound
+    #   words.
+    #
+    #   Omit this parameter for the [Add a custom word](#addword) method.
+    # @param sounds_like [Array[String]] _For a custom model that is based on a previous-generation model_, an array of
+    #   sounds-like pronunciations for the custom word. Specify how words that are
+    #   difficult to pronounce, foreign words, acronyms, and so on can be pronounced by
+    #   users.
     #   * For a word that is not in the service's base vocabulary, omit the parameter to
     #   have the service automatically generate a sounds-like pronunciation for the word.
     #   * For a word that is in the service's base vocabulary, use the parameter to
@@ -2258,6 +2367,10 @@ module IBMWatson
     #
     #   A word can have at most five sounds-like pronunciations. A pronunciation can
     #   include at most 40 characters not including spaces.
+    #
+    #   _For a custom model that is based on a next-generation model_, omit this field.
+    #   Custom models based on next-generation models do not support the `sounds_like`
+    #   field. The service ignores the field.
     # @param display_as [String] An alternative spelling for the custom word when it appears in a transcript. Use
     #   the parameter when you want the word to have a spelling that is different from its
     #   usual representation or from its spelling in corpora training data.
@@ -2332,11 +2445,12 @@ module IBMWatson
     # Delete a custom word.
     # Deletes a custom word from a custom language model. You can remove any word that
     #   you added to the custom model's words resource via any means. However, if the word
-    #   also exists in the service's base vocabulary, the service removes only the custom
-    #   pronunciation for the word; the word remains in the base vocabulary. Removing a
+    #   also exists in the service's base vocabulary, the service removes the word only
+    #   from the words resource; the word remains in the base vocabulary. Removing a
     #   custom word does not affect the custom model until you train the model with the
-    #   **Train a custom language model** method. You must use credentials for the
-    #   instance of the service that owns a model to delete its words.
+    #   [Train a custom language model](#trainlanguagemodel) method. You must use
+    #   credentials for the instance of the service that owns a model to delete its words.
+    #
     #
     #   **See also:** [Deleting a word from a custom language
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageWords#deleteWord).
@@ -2374,13 +2488,17 @@ module IBMWatson
     ##
     # @!method list_grammars(customization_id:)
     # List grammars.
-    # Lists information about all grammars from a custom language model. The information
-    #   includes the total number of out-of-vocabulary (OOV) words, name, and status of
-    #   each grammar. You must use credentials for the instance of the service that owns a
-    #   model to list its grammars.
+    # Lists information about all grammars from a custom language model. For each
+    #   grammar, the information includes the name, status, and (for grammars that are
+    #   based on previous-generation models) the total number of out-of-vocabulary (OOV)
+    #   words. You must use credentials for the instance of the service that owns a model
+    #   to list its grammars.
     #
-    #   **See also:** [Listing grammars from a custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageGrammars#listGrammars).
+    #   **See also:**
+    #   * [Listing grammars from a custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageGrammars#listGrammars)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -2411,8 +2529,8 @@ module IBMWatson
     #   UTF-8 format that defines the grammar. Use multiple requests to submit multiple
     #   grammar files. You must use credentials for the instance of the service that owns
     #   a model to add a grammar to it. Adding a grammar does not affect the custom
-    #   language model until you train the model for the new data by using the **Train a
-    #   custom language model** method.
+    #   language model until you train the model for the new data by using the [Train a
+    #   custom language model](#trainlanguagemodel) method.
     #
     #   The call returns an HTTP 201 response code if the grammar is valid. The service
     #   then asynchronously processes the contents of the grammar and automatically
@@ -2420,33 +2538,39 @@ module IBMWatson
     #   to complete depending on the size and complexity of the grammar, as well as the
     #   current load on the service. You cannot submit requests to add additional
     #   resources to the custom model or to train the model until the service's analysis
-    #   of the grammar for the current request completes. Use the **Get a grammar** method
-    #   to check the status of the analysis.
-    #
-    #   The service populates the model's words resource with any word that is recognized
-    #   by the grammar that is not found in the model's base vocabulary. These are
-    #   referred to as out-of-vocabulary (OOV) words. You can use the **List custom
-    #   words** method to examine the words resource and use other words-related methods
-    #   to eliminate typos and modify how words are pronounced as needed.
+    #   of the grammar for the current request completes. Use the [Get a
+    #   grammar](#getgrammar) method to check the status of the analysis.
+    #
+    #   _For grammars that are based on previous-generation models,_ the service populates
+    #   the model's words resource with any word that is recognized by the grammar that is
+    #   not found in the model's base vocabulary. These are referred to as
+    #   out-of-vocabulary (OOV) words. You can use the [List custom words](#listwords)
+    #   method to examine the words resource and use other words-related methods to
+    #   eliminate typos and modify how words are pronounced as needed. _For grammars that
+    #   are based on next-generation models,_ the service extracts no OOV words from the
+    #   grammars.
     #
     #   To add a grammar that has the same name as an existing grammar, set the
     #   `allow_overwrite` parameter to `true`; otherwise, the request fails. Overwriting
     #   an existing grammar causes the service to process the grammar file and extract OOV
     #   words anew. Before doing so, it removes any OOV words associated with the existing
     #   grammar from the model's words resource unless they were also added by another
-    #   resource or they have been modified in some way with the **Add custom words** or
-    #   **Add a custom word** method.
+    #   resource or they have been modified in some way with the [Add custom
+    #   words](#addwords) or [Add a custom word](#addword) method.
     #
-    #   The service limits the overall amount of data that you can add to a custom model
-    #   to a maximum of 10 million total words from all sources combined. Also, you can
-    #   add no more than 90 thousand OOV words to a model. This includes words that the
-    #   service extracts from corpora and grammars and words that you add directly.
+    #   _For grammars that are based on previous-generation models,_ the service limits
+    #   the overall amount of data that you can add to a custom model to a maximum of 10
+    #   million total words from all sources combined. Also, you can add no more than 90
+    #   thousand OOV words to a model. This includes words that the service extracts from
+    #   corpora and grammars and words that you add directly.
     #
     #   **See also:**
     #   * [Understanding
     #   grammars](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-grammarUnderstand#grammarUnderstand)
     #   * [Add a grammar to the custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-grammarAdd#addGrammar).
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-grammarAdd#addGrammar)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -2465,7 +2589,7 @@ module IBMWatson
     #   words that are added or modified by the user.
     #   * Do not use the name `base_lm` or `default_lm`. Both names are reserved for
     #   future use by the service.
-    # @param grammar_file [String] A plain text file that contains the grammar in the format specified by the
+    # @param grammar_file [File] A plain text file that contains the grammar in the format specified by the
     #   `Content-Type` header. Encode the file in UTF-8 (ASCII is a subset of UTF-8).
     #   Using any other encoding can lead to issues when compiling the grammar or to
     #   unexpected results in decoding. The service ignores an encoding that is specified
@@ -2520,13 +2644,17 @@ module IBMWatson
     ##
     # @!method get_grammar(customization_id:, grammar_name:)
     # Get a grammar.
-    # Gets information about a grammar from a custom language model. The information
-    #   includes the total number of out-of-vocabulary (OOV) words, name, and status of
-    #   the grammar. You must use credentials for the instance of the service that owns a
-    #   model to list its grammars.
+    # Gets information about a grammar from a custom language model. For each grammar,
+    #   the information includes the name, status, and (for grammars that are based on
+    #   previous-generation models) the total number of out-of-vocabulary (OOV) words. You
+    #   must use credentials for the instance of the service that owns a model to list its
+    #   grammars.
     #
-    #   **See also:** [Listing grammars from a custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageGrammars#listGrammars).
+    #   **See also:**
+    #   * [Listing grammars from a custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageGrammars#listGrammars)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -2556,16 +2684,21 @@ module IBMWatson
     ##
     # @!method delete_grammar(customization_id:, grammar_name:)
     # Delete a grammar.
-    # Deletes an existing grammar from a custom language model. The service removes any
-    #   out-of-vocabulary (OOV) words associated with the grammar from the custom model's
-    #   words resource unless they were also added by another resource or they were
-    #   modified in some way with the **Add custom words** or **Add a custom word**
-    #   method. Removing a grammar does not affect the custom model until you train the
-    #   model with the **Train a custom language model** method. You must use credentials
-    #   for the instance of the service that owns a model to delete its grammar.
-    #
-    #   **See also:** [Deleting a grammar from a custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageGrammars#deleteGrammar).
+    # Deletes an existing grammar from a custom language model. _For grammars that are
+    #   based on previous-generation models,_ the service removes any out-of-vocabulary
+    #   (OOV) words associated with the grammar from the custom model's words resource
+    #   unless they were also added by another resource or they were modified in some way
+    #   with the [Add custom words](#addwords) or [Add a custom word](#addword) method.
+    #   Removing a grammar does not affect the custom model until you train the model with
+    #   the [Train a custom language model](#trainlanguagemodel) method. You must use
+    #   credentials for the instance of the service that owns a model to delete its
+    #   grammar.
+    #
+    #   **See also:**
+    #   * [Deleting a grammar from a custom language
+    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageGrammars#deleteGrammar)
+    #   * [Language support for
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param customization_id [String] The customization ID (GUID) of the custom language model that is to be used for
     #   the request. You must make the request with credentials for the instance of the
     #   service that owns the custom model.
@@ -2608,6 +2741,18 @@ module IBMWatson
     #   do not lose any models, but you cannot create any more until your model count is
     #   below the limit.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
+    #   **Important:** Effective 15 March 2022, previous-generation models for all
+    #   languages other than Arabic and Japanese are deprecated. The deprecated models
+    #   remain available until 15 September 2022, when they will be removed from the
+    #   service and the documentation. You must migrate to the equivalent next-generation
+    #   model by the end of service date. For more information, see [Migrating to
+    #   next-generation
+    #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-migrate).
+    #
+    #
     #   **See also:** [Create a custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-acoustic#createModel-acoustic).
     # @param name [String] A user-defined name for the new custom acoustic model. Use a name that is unique
@@ -2622,7 +2767,7 @@ module IBMWatson
     #
     #   To determine whether a base model supports acoustic model customization, refer to
     #   [Language support for
-    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-customization#languageSupport).
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @param description [String] A description of the new custom acoustic model. Use a localized description that
     #   matches the language of the custom model.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
@@ -2663,16 +2808,21 @@ module IBMWatson
     #   all languages. You must use credentials for the instance of the service that owns
     #   a model to list information about it.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:** [Listing custom acoustic
     #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAcousticModels#listModels-acoustic).
     # @param language [String] The identifier of the language for which custom language or custom acoustic models
-    #   are to be returned. Omit the parameter to see all custom language or custom
-    #   acoustic models that are owned by the requesting credentials. (**Note:** The
-    #   identifier `ar-AR` is deprecated; use `ar-MS` instead.)
+    #   are to be returned. Specify the five-character language identifier; for example,
+    #   specify `en-US` to see all custom language or custom acoustic models that are
+    #   based on US English models. Omit the parameter to see all custom language or
+    #   custom acoustic models that are owned by the requesting credentials. (**Note:**
+    #   The identifier `ar-AR` is deprecated; use `ar-MS` instead.)
     #
     #   To determine the languages for which customization is available, see [Language
     #   support for
-    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-customization#languageSupport).
+    #   customization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-support).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_acoustic_models(language: nil)
       headers = {
@@ -2702,6 +2852,9 @@ module IBMWatson
     # Gets information about a specified custom acoustic model. You must use credentials
     #   for the instance of the service that owns a model to list information about it.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:** [Listing custom acoustic
     #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAcousticModels#listModels-acoustic).
     # @param customization_id [String] The customization ID (GUID) of the custom acoustic model that is to be used for
@@ -2735,6 +2888,9 @@ module IBMWatson
     #   processed. You must use credentials for the instance of the service that owns a
     #   model to delete it.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:** [Deleting a custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAcousticModels#deleteModel-acoustic).
     # @param customization_id [String] The customization ID (GUID) of the custom acoustic model that is to be used for
@@ -2779,14 +2935,14 @@ module IBMWatson
     #   audio. The method returns an HTTP 200 response code to indicate that the training
     #   process has begun.
     #
-    #   You can monitor the status of the training by using the **Get a custom acoustic
-    #   model** method to poll the model's status. Use a loop to check the status once a
-    #   minute. The method returns an `AcousticModel` object that includes `status` and
-    #   `progress` fields. A status of `available` indicates that the custom model is
-    #   trained and ready to use. The service cannot train a model while it is handling
-    #   another request for the model. The service cannot accept subsequent training
-    #   requests, or requests to add new audio resources, until the existing training
-    #   request completes.
+    #   You can monitor the status of the training by using the [Get a custom acoustic
+    #   model](#getacousticmodel) method to poll the model's status. Use a loop to check
+    #   the status once a minute. The method returns an `AcousticModel` object that
+    #   includes `status` and `progress` fields. A status of `available` indicates that
+    #   the custom model is trained and ready to use. The service cannot train a model
+    #   while it is handling another request for the model. The service cannot accept
+    #   subsequent training requests, or requests to add new audio resources, until the
+    #   existing training request completes.
     #
     #   You can use the optional `custom_language_model_id` parameter to specify the GUID
     #   of a separately created custom language model that is to be used during training.
@@ -2797,6 +2953,9 @@ module IBMWatson
     #   same version of the same base model, and the custom language model must be fully
     #   trained and available.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:**
     #   * [Train the custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-acoustic#trainModel-acoustic)
@@ -2868,6 +3027,9 @@ module IBMWatson
     #   request completes. You must use credentials for the instance of the service that
     #   owns a model to reset it.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:** [Resetting a custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAcousticModels#resetModel-acoustic).
     # @param customization_id [String] The customization ID (GUID) of the custom acoustic model that is to be used for
@@ -2906,14 +3068,15 @@ module IBMWatson
     #
     #   The method returns an HTTP 200 response code to indicate that the upgrade process
     #   has begun successfully. You can monitor the status of the upgrade by using the
-    #   **Get a custom acoustic model** method to poll the model's status. The method
-    #   returns an `AcousticModel` object that includes `status` and `progress` fields.
-    #   Use a loop to check the status once a minute. While it is being upgraded, the
-    #   custom model has the status `upgrading`. When the upgrade is complete, the model
-    #   resumes the status that it had prior to upgrade. The service cannot upgrade a
-    #   model while it is handling another request for the model. The service cannot
-    #   accept subsequent requests for the model until the existing upgrade request
-    #   completes.
+    #   [Get a custom acoustic model](#getacousticmodel) method to poll the model's
+    #   status. The method returns an `AcousticModel` object that includes `status` and
+    #   `progress` fields. Use a loop to check the status once a minute.
+    #
+    #   While it is being upgraded, the custom model has the status `upgrading`. When the
+    #   upgrade is complete, the model resumes the status that it had prior to upgrade.
+    #   The service cannot upgrade a model while it is handling another request for the
+    #   model. The service cannot accept subsequent requests for the model until the
+    #   existing upgrade request completes.
     #
     #   If the custom acoustic model was trained with a separately created custom language
     #   model, you must use the `custom_language_model_id` parameter to specify the GUID
@@ -2921,6 +3084,9 @@ module IBMWatson
     #   the custom acoustic model can be upgraded. Omit the parameter if the custom
     #   acoustic model was not trained with a custom language model.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:** [Upgrading a custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade#custom-upgrade-acoustic).
     # @param customization_id [String] The customization ID (GUID) of the custom acoustic model that is to be used for
@@ -2976,6 +3142,9 @@ module IBMWatson
     #   to a request to add it to the custom acoustic model. You must use credentials for
     #   the instance of the service that owns a model to list its audio resources.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:** [Listing audio resources for a custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAudio#listAudio).
     # @param customization_id [String] The customization ID (GUID) of the custom acoustic model that is to be used for
@@ -3008,8 +3177,8 @@ module IBMWatson
     #   the acoustic characteristics of the audio that you plan to transcribe. You must
     #   use credentials for the instance of the service that owns a model to add an audio
     #   resource to it. Adding audio data does not affect the custom acoustic model until
-    #   you train the model for the new data by using the **Train a custom acoustic
-    #   model** method.
+    #   you train the model for the new data by using the [Train a custom acoustic
+    #   model](#trainacousticmodel) method.
     #
     #   You can add individual audio files or an archive file that contains multiple audio
     #   files. Adding multiple audio files via a single archive file is significantly more
@@ -3034,11 +3203,14 @@ module IBMWatson
     #   upgrade the model until the service's analysis of all audio resources for current
     #   requests completes.
     #
-    #   To determine the status of the service's analysis of the audio, use the **Get an
-    #   audio resource** method to poll the status of the audio. The method accepts the
-    #   customization ID of the custom model and the name of the audio resource, and it
-    #   returns the status of the resource. Use a loop to check the status of the audio
-    #   every few seconds until it becomes `ok`.
+    #   To determine the status of the service's analysis of the audio, use the [Get an
+    #   audio resource](#getaudio) method to poll the status of the audio. The method
+    #   accepts the customization ID of the custom model and the name of the audio
+    #   resource, and it returns the status of the resource. Use a loop to check the
+    #   status of the audio every few seconds until it becomes `ok`.
+    #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
     #
     #   **See also:** [Add audio to the custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-acoustic#addAudio).
@@ -3133,7 +3305,7 @@ module IBMWatson
     #   For an archive-type resource, the media type of the archive file. For more
     #   information, see **Content types for archive-type resources** in the method
     #   description.
-    # @param contained_content_type [String] **For an archive-type resource,** specify the format of the audio files that are
+    # @param contained_content_type [String] _For an archive-type resource_, specify the format of the audio files that are
     #   contained in the archive file if they are of type `audio/alaw`, `audio/basic`,
     #   `audio/l16`, or `audio/mulaw`. Include the `rate`, `channels`, and `endianness`
     #   parameters where necessary. In this case, all audio files that are contained in
@@ -3147,7 +3319,7 @@ module IBMWatson
     #   speech recognition. For more information, see **Content types for audio-type
     #   resources** in the method description.
     #
-    #   **For an audio-type resource,** omit the header.
+    #   _For an audio-type resource_, omit the header.
     # @param allow_overwrite [Boolean] If `true`, the specified audio resource overwrites an existing audio resource with
     #   the same name. If `false`, the request fails if an audio resource with the same
     #   name already exists. The parameter has no effect if an audio resource with the
@@ -3192,9 +3364,9 @@ module IBMWatson
     # Gets information about an audio resource from a custom acoustic model. The method
     #   returns an `AudioListing` object whose fields depend on the type of audio resource
     #   that you specify with the method's `audio_name` parameter:
-    #   * **For an audio-type resource,** the object's fields match those of an
+    #   * _For an audio-type resource_, the object's fields match those of an
     #   `AudioResource` object: `duration`, `name`, `details`, and `status`.
-    #   * **For an archive-type resource,** the object includes a `container` field whose
+    #   * _For an archive-type resource_, the object includes a `container` field whose
     #   fields match those of an `AudioResource` object. It also includes an `audio`
     #   field, which contains an array of `AudioResource` objects that provides
     #   information about the audio files that are contained in the archive.
@@ -3202,14 +3374,17 @@ module IBMWatson
     #   The information includes the status of the specified audio resource. The status is
     #   important for checking the service's analysis of a resource that you add to the
     #   custom model.
-    #   * For an audio-type resource, the `status` field is located in the `AudioListing`
-    #   object.
-    #   * For an archive-type resource, the `status` field is located in the
+    #   * _For an audio-type resource_, the `status` field is located in the
+    #   `AudioListing` object.
+    #   * _For an archive-type resource_, the `status` field is located in the
     #   `AudioResource` object that is returned in the `container` field.
     #
     #   You must use credentials for the instance of the service that owns a model to list
     #   its audio resources.
     #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
+    #
     #   **See also:** [Listing audio resources for a custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAudio#listAudio).
     # @param customization_id [String] The customization ID (GUID) of the custom acoustic model that is to be used for
@@ -3246,10 +3421,14 @@ module IBMWatson
     #   not allow deletion of individual files from an archive resource.
     #
     #   Removing an audio resource does not affect the custom model until you train the
-    #   model on its updated data by using the **Train a custom acoustic model** method.
-    #   You can delete an existing audio resource from a model while a different resource
-    #   is being added to the model. You must use credentials for the instance of the
-    #   service that owns a model to delete its audio resources.
+    #   model on its updated data by using the [Train a custom acoustic
+    #   model](#trainacousticmodel) method. You can delete an existing audio resource from
+    #   a model while a different resource is being added to the model. You must use
+    #   credentials for the instance of the service that owns a model to delete its audio
+    #   resources.
+    #
+    #   **Note:** Acoustic model customization is supported only for use with
+    #   previous-generation models. It is not supported for next-generation models.
     #
     #   **See also:** [Deleting an audio resource from a custom acoustic
     #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAudio#deleteAudio).