ibm_watson 1.3.0 → 2.0.0.rc1

data/lib/ibm_watson/natural_language_understanding_v1.rb

@@ -13,14 +13,16 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+#
+# IBM OpenAPI SDK Code Generator Version: 3.17.0-8d569e8f-20201030-142059
+#
 # Analyze various features of text content at scale. Provide text, raw HTML, or a public
 # URL and IBM Watson Natural Language Understanding will give you results for the features
 # you request. The service cleans HTML content before analysis by default, so the results
 # can ignore most advertisements and other unwanted content.
 #
 # You can create [custom
-# models](https://cloud.ibm.com/docs/services/natural-language-understanding?topic=natural-language-understanding-customizing)
+# models](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing)
 # with Watson Knowledge Studio to detect custom entities and relations in Natural Language
 # Understanding.
 
@@ -36,37 +38,36 @@ module IBMWatson
   # The Natural Language Understanding V1 service.
   class NaturalLanguageUnderstandingV1 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "natural_language_understanding"
+    DEFAULT_SERVICE_URL = "https://api.us-south.natural-language-understanding.watson.cloud.ibm.com"
+    attr_accessor :version
     ##
     # @!method initialize(args)
     # Construct a new client for the Natural Language Understanding service.
     #
     # @param args [Hash] The args to initialize with
-    # @option args version [String] The API version date to use with the service, in
-    #   "YYYY-MM-DD" format. Whenever the API is changed in a backwards
-    #   incompatible way, a new minor version of the API is released.
-    #   The service uses the API version for the date you specify, or
-    #   the most recent version before that date. Note that you should
-    #   not programmatically specify the current date at runtime, in
-    #   case the API has been updated since your application's release.
-    #   Instead, specify a version date that is compatible with your
-    #   application, and don't change it until your application is
-    #   ready for a later version.
+    # @option args version [String] Release date of the API version you want to use. Specify dates in YYYY-MM-DD
+    #   format. The current version is `2020-08-01`.
     # @option args service_url [String] The base service URL to use when contacting the service.
     #   The base service_url may differ between IBM Cloud regions.
     # @option args authenticator [Object] The Authenticator instance to be configured for this service.
+    # @option args service_name [String] The name of the service to configure. Will be used as the key to load
+    #   any external configuration, if applicable.
     def initialize(args = {})
       @__async_initialized__ = false
       defaults = {}
-      defaults[:version] = nil
-      defaults[:service_url] = "https://gateway.watsonplatform.net/natural-language-understanding/api"
+      defaults[:service_url] = DEFAULT_SERVICE_URL
+      defaults[:service_name] = DEFAULT_SERVICE_NAME
       defaults[:authenticator] = nil
+      defaults[:version] = nil
+      user_service_url = args[:service_url] unless args[:service_url].nil?
       args = defaults.merge(args)
       @version = args[:version]
       raise ArgumentError.new("version must be provided") if @version.nil?
 
-      args[:service_name] = "natural_language_understanding"
       args[:authenticator] = IBMCloudSdkCore::ConfigBasedAuthenticatorFactory.new.get_authenticator(service_name: args[:service_name]) if args[:authenticator].nil?
       super
+      @service_url = user_service_url unless user_service_url.nil?
     end
 
     #########################
@@ -86,11 +87,12 @@ module IBMWatson
     #   - Relations
     #   - Semantic roles
     #   - Sentiment
-    #   - Syntax (Experimental).
+    #   - Syntax
+    #   - Summarization (Experimental)
     #
     #   If a language for the input text is not specified with the `language` parameter,
     #   the service [automatically detects the
-    #   language](https://cloud.ibm.com/docs/services/natural-language-understanding?topic=natural-language-understanding-detectable-languages).
+    #   language](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-detectable-languages).
     # @param features [Features] Specific features to analyze the document for.
     # @param text [String] The plain text to analyze. One of the `text`, `html`, or `url` parameters is
     #   required.
@@ -98,12 +100,11 @@ module IBMWatson
     #   required.
     # @param url [String] The webpage to analyze. One of the `text`, `html`, or `url` parameters is
     #   required.
-    # @param clean [Boolean] Set this to `false` to disable webpage cleaning. To learn more about webpage
-    #   cleaning, see the [Analyzing
-    #   webpages](https://cloud.ibm.com/docs/services/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages)
-    #   documentation.
+    # @param clean [Boolean] Set this to `false` to disable webpage cleaning. For more information about
+    #   webpage cleaning, see [Analyzing
+    #   webpages](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages).
     # @param xpath [String] An [XPath
-    #   query](https://cloud.ibm.com/docs/services/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages#xpath)
+    #   query](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages#xpath)
     #   to perform on `html` or `url` input. Results of the query will be appended to the
     #   cleaned webpage text before it is analyzed. To analyze only the results of the
     #   XPath query, set the `clean` parameter to `false`.
@@ -111,12 +112,13 @@ module IBMWatson
     # @param return_analyzed_text [Boolean] Whether or not to return the analyzed text.
     # @param language [String] ISO 639-1 code that specifies the language of your text. This overrides automatic
     #   language detection. Language support differs depending on the features you include
-    #   in your analysis. See [Language
-    #   support](https://cloud.ibm.com/docs/services/natural-language-understanding?topic=natural-language-understanding-language-support)
-    #   for more information.
+    #   in your analysis. For more information, see [Language
+    #   support](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-language-support).
     # @param limit_text_characters [Fixnum] Sets the maximum number of characters that are processed by the service.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def analyze(features:, text: nil, html: nil, url: nil, clean: nil, xpath: nil, fallback_to_raw: nil, return_analyzed_text: nil, language: nil, limit_text_characters: nil)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("features must be provided") if features.nil?
 
       headers = {
@@ -161,10 +163,12 @@ module IBMWatson
     # @!method list_models
     # List models.
     # Lists Watson Knowledge Studio [custom entities and relations
-    #   models](https://cloud.ibm.com/docs/services/natural-language-understanding?topic=natural-language-understanding-customizing)
+    #   models](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing)
     #   that are deployed to your Natural Language Understanding service.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_models
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       headers = {
       }
       sdk_headers = Common.new.get_sdk_headers("natural-language-understanding", "V1", "list_models")
@@ -193,6 +197,8 @@ module IBMWatson
     # @param model_id [String] Model ID of the model to delete.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def delete_model(model_id:)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("model_id must be provided") if model_id.nil?
 
       headers = {

data/lib/ibm_watson/personality_insights_v3.rb

@@ -13,7 +13,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+#
+# IBM OpenAPI SDK Code Generator Version: 3.17.0-8d569e8f-20201030-142059
+#
 # The IBM Watson™ Personality Insights service enables applications to derive
 # insights from social media, enterprise data, or other digital communications. The
 # service uses linguistic analytics to infer individuals' intrinsic personality
@@ -47,37 +49,41 @@ module IBMWatson
   # The Personality Insights V3 service.
   class PersonalityInsightsV3 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "personality_insights"
+    DEFAULT_SERVICE_URL = "https://api.us-south.personality-insights.watson.cloud.ibm.com"
+    attr_accessor :version
     ##
     # @!method initialize(args)
     # Construct a new client for the Personality Insights service.
     #
     # @param args [Hash] The args to initialize with
-    # @option args version [String] The API version date to use with the service, in
-    #   "YYYY-MM-DD" format. Whenever the API is changed in a backwards
-    #   incompatible way, a new minor version of the API is released.
-    #   The service uses the API version for the date you specify, or
-    #   the most recent version before that date. Note that you should
-    #   not programmatically specify the current date at runtime, in
-    #   case the API has been updated since your application's release.
-    #   Instead, specify a version date that is compatible with your
-    #   application, and don't change it until your application is
-    #   ready for a later version.
+    # @option args version [String] Release date of the version of the API you want to use. Specify dates in
+    #   YYYY-MM-DD format. The current version is `2017-10-13`.
     # @option args service_url [String] The base service URL to use when contacting the service.
     #   The base service_url may differ between IBM Cloud regions.
     # @option args authenticator [Object] The Authenticator instance to be configured for this service.
+    # @option args service_name [String] The name of the service to configure. Will be used as the key to load
+    #   any external configuration, if applicable.
+    #
+    # @deprecated On 1 December 2021, Personality Insights will no longer be available.
+    #   Consider migrating to Watson Natural Language Understanding.
+    #   For more information, see [Personality Insights Deprecation](https://github.com/watson-developer-cloud/ruby-sdk/tree/master#personality-insights-deprecation).
     def initialize(args = {})
+      warn "On 1 December 2021, Personality Insights will no longer be available. For more information, see the README."
       @__async_initialized__ = false
       defaults = {}
-      defaults[:version] = nil
-      defaults[:service_url] = "https://gateway.watsonplatform.net/personality-insights/api"
+      defaults[:service_url] = DEFAULT_SERVICE_URL
+      defaults[:service_name] = DEFAULT_SERVICE_NAME
       defaults[:authenticator] = nil
+      defaults[:version] = nil
+      user_service_url = args[:service_url] unless args[:service_url].nil?
       args = defaults.merge(args)
       @version = args[:version]
       raise ArgumentError.new("version must be provided") if @version.nil?
 
-      args[:service_name] = "personality_insights"
       args[:authenticator] = IBMCloudSdkCore::ConfigBasedAuthenticatorFactory.new.get_authenticator(service_name: args[:service_name]) if args[:authenticator].nil?
       super
+      @service_url = user_service_url unless user_service_url.nil?
     end
 
     #########################
@@ -164,6 +170,8 @@ module IBMWatson
     #   default, no consumption preferences are returned.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def profile(content:, accept:, content_type: nil, content_language: nil, accept_language: nil, raw_scores: nil, csv_headers: nil, consumption_preferences: nil)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("content must be provided") if content.nil?
 
       raise ArgumentError.new("accept must be provided") if accept.nil?

data/lib/ibm_watson/speech_to_text_v1.rb

@@ -13,13 +13,15 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
-# The IBM® Speech to Text service provides APIs that use IBM's 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. For
-# most languages, the service supports two sampling rates, broadband and narrowband. It
-# returns all JSON response content in the UTF-8 character set.
+#
+# IBM OpenAPI SDK Code Generator Version: 3.17.0-8d569e8f-20201030-142059
+#
+# 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
+# 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. For most languages, the service supports two sampling rates, broadband and
+# narrowband. It returns all JSON response content in the UTF-8 character set.
 #
 # For speech recognition, the service supports synchronous and asynchronous HTTP
 # Representational State Transfer (REST) interfaces. It also supports a WebSocket
@@ -34,9 +36,9 @@
 # is a formal language specification that lets you restrict the phrases that the service
 # can recognize.
 #
-# Language model customization is generally available for production use with most
-# supported languages. Acoustic model customization is beta functionality that is
-# available for all supported languages.
+# Language model customization and acoustic model customization are generally available
+# for production use with all language models that are generally available. Grammars are
+# beta functionality for all language models that support language model customization.
 
 require "concurrent"
 require "erb"
@@ -50,6 +52,8 @@ module IBMWatson
   # The Speech to Text V1 service.
   class SpeechToTextV1 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "speech_to_text"
+    DEFAULT_SERVICE_URL = "https://api.us-south.speech-to-text.watson.cloud.ibm.com"
     ##
     # @!method initialize(args)
     # Construct a new client for the Speech to Text service.
@@ -58,15 +62,19 @@ module IBMWatson
     # @option args service_url [String] The base service URL to use when contacting the service.
     #   The base service_url may differ between IBM Cloud regions.
     # @option args authenticator [Object] The Authenticator instance to be configured for this service.
+    # @option args service_name [String] The name of the service to configure. Will be used as the key to load
+    #   any external configuration, if applicable.
     def initialize(args = {})
       @__async_initialized__ = false
       defaults = {}
-      defaults[:service_url] = "https://stream.watsonplatform.net/speech-to-text/api"
+      defaults[:service_url] = DEFAULT_SERVICE_URL
+      defaults[:service_name] = DEFAULT_SERVICE_NAME
       defaults[:authenticator] = nil
+      user_service_url = args[:service_url] unless args[:service_url].nil?
       args = defaults.merge(args)
-      args[:service_name] = "speech_to_text"
       args[:authenticator] = IBMCloudSdkCore::ConfigBasedAuthenticatorFactory.new.get_authenticator(service_name: args[:service_name]) if args[:authenticator].nil?
       super
+      @service_url = user_service_url unless user_service_url.nil?
     end
 
     #########################
@@ -78,7 +86,8 @@ module IBMWatson
     # List models.
     # Lists all language models that are available for use with the service. The
     #   information includes the name of the model and its minimum sampling rate in Hertz,
-    #   among other things.
+    #   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:** [Languages and
     #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models#models).
@@ -135,7 +144,7 @@ module IBMWatson
     #########################
 
     ##
-    # @!method recognize(audio:, content_type: nil, model: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil)
+    # @!method recognize(audio:, content_type: nil, model: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil, speech_detector_sensitivity: nil, background_audio_suppression: nil)
     # Recognize audio.
     # Sends audio and returns transcription results for a recognition request. You can
     #   pass a maximum of 100 MB and a minimum of 100 bytes of audio with a request. The
@@ -223,7 +232,7 @@ module IBMWatson
     #
     #   **See also:** [Making a multipart HTTP
     #   request](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-http#HTTP-multi).
-    # @param audio [String] The audio to transcribe.
+    # @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. See
@@ -277,8 +286,14 @@ module IBMWatson
     # @param keywords [Array[String]] An array of keyword strings to spot in the audio. Each keyword string can include
     #   one or more string tokens. Keywords are spotted only in the final results, not in
     #   interim hypotheses. If you specify any keywords, you must also specify a keywords
-    #   threshold. You can spot a maximum of 1000 keywords. Omit the parameter or specify
-    #   an empty array if you do not need to spot keywords. See [Keyword
+    #   threshold. Omit the parameter or specify an empty array if you do not need to spot
+    #   keywords.
+    #
+    #   You can spot a maximum of 1000 keywords with a single request. A single keyword
+    #   can have a maximum length of 1024 characters, though the maximum effective length
+    #   for double-byte languages might be shorter. Keywords are case-insensitive.
+    #
+    #   See [Keyword
     #   spotting](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#keyword_spotting).
     # @param keywords_threshold [Float] A confidence value that is the lower bound for spotting a keyword. A word is
     #   considered to match a keyword if its confidence is greater than or equal to the
@@ -323,11 +338,9 @@ module IBMWatson
     #   parameter to be `true`, regardless of whether you specify `false` for the
     #   parameter.
     #
-    #   **Note:** Applies to US English, Japanese, and Spanish (both broadband and
-    #   narrowband models) and UK English (narrowband model) transcription only. To
-    #   determine whether a language model supports speaker labels, you can also use the
-    #   **Get a model** method and check that the attribute `speaker_labels` is set to
-    #   `true`.
+    #   **Note:** Applies to US English, Australian English, German, Japanese, Korean, and
+    #   Spanish (both broadband and narrowband models) and UK English (narrowband model)
+    #   transcription only.
     #
     #   See [Speaker
     #   labels](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#speaker_labels).
@@ -388,8 +401,33 @@ module IBMWatson
     #
     #   See [Split transcript at phrase
     #   end](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#split_transcript).
+    # @param speech_detector_sensitivity [Float] The sensitivity of speech activity detection that the service is to perform. Use
+    #   the parameter to suppress word insertions from music, coughing, and other
+    #   non-speech events. The service biases the audio it passes for speech recognition
+    #   by evaluating the input audio against prior models of speech and non-speech
+    #   activity.
+    #
+    #   Specify a value between 0.0 and 1.0:
+    #   * 0.0 suppresses all audio (no speech is transcribed).
+    #   * 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 Activity
+    #   Detection](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-input#detection).
+    # @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.
+    #
+    #   Specify a value in the range of 0.0 to 1.0:
+    #   * 0.0 (the default) provides no suppression (background audio suppression is
+    #   disabled).
+    #   * 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 [Speech Activity
+    #   Detection](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-input#detection).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
-    def recognize(audio:, content_type: nil, model: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil)
+    def recognize(audio:, content_type: nil, model: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil, speech_detector_sensitivity: nil, background_audio_suppression: nil)
       raise ArgumentError.new("audio must be provided") if audio.nil?
 
       headers = {
@@ -420,7 +458,9 @@ module IBMWatson
         "redaction" => redaction,
         "audio_metrics" => audio_metrics,
         "end_of_phrase_silence_time" => end_of_phrase_silence_time,
-        "split_transcript_at_phrase_end" => split_transcript_at_phrase_end
+        "split_transcript_at_phrase_end" => split_transcript_at_phrase_end,
+        "speech_detector_sensitivity" => speech_detector_sensitivity,
+        "background_audio_suppression" => background_audio_suppression
       }
 
       data = audio
@@ -439,7 +479,7 @@ module IBMWatson
     end
 
     ##
-    # @!method recognize_using_websocket(content_type: nil,recognize_callback:,audio: nil,chunk_data: false,model: nil,customization_id: nil,acoustic_customization_id: nil,customization_weight: nil,base_model_version: nil,inactivity_timeout: nil,interim_results: nil,keywords: nil,keywords_threshold: nil,max_alternatives: nil,word_alternatives_threshold: nil,word_confidence: nil,timestamps: nil,profanity_filter: nil,smart_formatting: nil,speaker_labels: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil)
+    # @!method recognize_using_websocket(content_type: nil,recognize_callback:,audio: nil,chunk_data: false,model: nil,customization_id: nil,acoustic_customization_id: nil,customization_weight: nil,base_model_version: nil,inactivity_timeout: nil,interim_results: nil,keywords: nil,keywords_threshold: nil,max_alternatives: nil,word_alternatives_threshold: nil,word_confidence: nil,timestamps: nil,profanity_filter: nil,smart_formatting: nil,speaker_labels: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil, speech_detector_sensitivity: nil, background_audio_suppression: nil)
     # Sends audio for speech recognition using web sockets.
     # @param content_type [String] The type of the input: audio/basic, audio/flac, audio/l16, audio/mp3, audio/mpeg, audio/mulaw, audio/ogg, audio/ogg;codecs=opus, audio/ogg;codecs=vorbis, audio/wav, audio/webm, audio/webm;codecs=opus, audio/webm;codecs=vorbis, or multipart/form-data.
     # @param recognize_callback [RecognizeCallback] The instance handling events returned from the service.
@@ -449,7 +489,7 @@ module IBMWatson
     # @param customization_id [String] The GUID of a custom language model that is to be used with the request. The base model of the specified custom language model must match the model specified with the `model` parameter. You must make the request with service credentials created for the instance of the service that owns the custom model. By default, no custom language model is used.
     # @param acoustic_customization_id [String] The GUID of a custom acoustic model that is to be used with the request. The base model of the specified custom acoustic model must match the model specified with the `model` parameter. You must make the request with service credentials created for the instance of the service that owns the custom model. By default, no custom acoustic model is used.
     # @param language_customization_id [String] The GUID of a custom language model that is to be used with the request. The base model of the specified custom language model must match the model specified with the `model` parameter. You must make the request with service credentials created for the instance of the service that owns the custom model. By default, no custom language model is used.
-    # @param base_model_version [String] The version of the specified base `model` that is to be used for speech recognition. Multiple versions of a base model can exist when a model is updated for internal improvements. The parameter is intended primarily for use with custom models that have been upgraded for a new base model. The default value depends on whether the parameter is used with or without a custom model. For more information, see [Base model version](https://console.bluemix.net/docs/services/speech-to-text/input.html#version).
+    # @param base_model_version [String] The version of the specified base `model` that is to be used for speech recognition. Multiple versions of a base model can exist when a model is updated for internal improvements. The parameter is intended primarily for use with custom models that have been upgraded for a new base model. The default value depends on whether the parameter is used with or without a custom model. For more information, see [Base model version](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-input#version).
     # @param inactivity_timeout [Integer] The time in seconds after which, if only silence (no speech) is detected in submitted audio, the connection is closed with a 400 error. Useful for stopping audio submission from a live microphone when a user simply walks away. Use `-1` for infinity.
     # @param interim_results [Boolean] Send back non-final previews of each "sentence" as it is being processed. These results are ignored in text mode.
     # @param keywords [Array<String>] Array of keyword strings to spot in the audio. Each keyword string can include one or more tokens. Keywords are spotted only in the final hypothesis, not in interim results. If you specify any keywords, you must also specify a keywords threshold. Omit the parameter or specify an empty array if you do not need to spot keywords.
@@ -460,13 +500,13 @@ module IBMWatson
     # @param timestamps [Boolean] If `true`, time alignment for each word is returned.
     # @param profanity_filter [Boolean] If `true` (the default), filters profanity from all output except for keyword results by replacing inappropriate words with a series of asterisks. Set the parameter to `false` to return results with no censoring. Applies to US English transcription only.
     # @param smart_formatting [Boolean] If `true`, converts dates, times, series of digits and numbers, phone numbers, currency values, and Internet addresses into more readable, conventional representations in the final transcript of a recognition request. If `false` (the default), no formatting is performed. Applies to US English transcription only.
-    # @param speaker_labels [Boolean] Indicates whether labels that identify which words were spoken by which participants in a multi-person exchange are to be included in the response. The default is `false`; no speaker labels are returned. Setting `speaker_labels` to `true` forces the `timestamps` parameter to be `true`, regardless of whether you specify `false` for the parameter.   To determine whether a language model supports speaker labels, use the `GET /v1/models` method and check that the attribute `speaker_labels` is set to `true`. You can also refer to [Speaker labels](https://console.bluemix.net/docs/services/speech-to-text/output.html#speaker_labels).
+    # @param speaker_labels [Boolean] Indicates whether labels that identify which words were spoken by which participants in a multi-person exchange are to be included in the response. The default is `false`; no speaker labels are returned. Setting `speaker_labels` to `true` forces the `timestamps` parameter to be `true`, regardless of whether you specify `false` for the parameter.   To determine whether a language model supports speaker labels, use the `GET /v1/models` method and check that the attribute `speaker_labels` is set to `true`. You can also refer to [Speaker labels](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#speaker_labels).
     # @param grammar_name [String] The name of a grammar that is to be used with the recognition request. If you
     #   specify a grammar, you must also use the `language_customization_id` parameter to
     #   specify the name of the custom language model for which the grammar is defined.
     #   The service recognizes only strings that are recognized by the specified grammar;
     #   it does not recognize other custom words from the model's words resource. See
-    #   [Grammars](https://cloud.ibm.com/docs/services/speech-to-text/output.html).
+    #   [Grammars](https://cloud.ibm.com/docs/speech-to-text/output.html).
     # @param redaction [Boolean] If `true`, the service redacts, or masks, numeric data from final transcripts. The
     #   feature redacts any number that has three or more consecutive digits by replacing
     #   each digit with an `X` character. It is intended to redact sensitive numeric data,
@@ -481,7 +521,7 @@ module IBMWatson
     #   **Note:** Applies to US English, Japanese, and Korean transcription only.
     #
     #   See [Numeric
-    #   redaction](https://cloud.ibm.com/docs/services/speech-to-text/output.html#redaction).
+    #   redaction](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#redaction).
     #
     # @param processing_metrics [Boolean] If `true`, requests processing metrics about the service's transcription of the
     #   input audio. The service returns processing metrics at the interval specified by
@@ -503,7 +543,7 @@ module IBMWatson
     # @return [WebSocketClient] Returns a new WebSocketClient object
     #
     #   See [Audio
-    #   metrics](https://cloud.ibm.com/docs/services/speech-to-text?topic=speech-to-text-metrics#audio_metrics).
+    #   metrics](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-metrics#audio_metrics).
     # @param end_of_phrase_silence_time [Float] If `true`, specifies the duration of the pause interval at which the service
     #   splits a transcript into multiple final results. If the service detects pauses or
     #   extended silence before it reaches the end of the audio stream, its response can
@@ -520,7 +560,7 @@ module IBMWatson
     #   Chinese is 0.6 seconds.
     #
     #   See [End of phrase silence
-    #   time](https://cloud.ibm.com/docs/services/speech-to-text?topic=speech-to-text-output#silence_time).
+    #   time](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#silence_time).
     # @param split_transcript_at_phrase_end [Boolean] If `true`, directs the service to split the transcript into multiple final results
     #   based on semantic features of the input, for example, at the conclusion of
     #   meaningful phrases such as sentences. The service bases its understanding of
@@ -530,7 +570,33 @@ module IBMWatson
     #   interval.
     #
     #   See [Split transcript at phrase
-    #   end](https://cloud.ibm.com/docs/services/speech-to-text?topic=speech-to-text-output#split_transcript).
+    #   end](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#split_transcript).
+    # @param speech_detector_sensitivity [Float] The sensitivity of speech activity detection that the service is to perform. Use
+    #   the parameter to suppress word insertions from music, coughing, and other
+    #   non-speech events. The service biases the audio it passes for speech recognition
+    #   by evaluating the input audio against prior models of speech and non-speech
+    #   activity.
+    #
+    #   Specify a value between 0.0 and 1.0:
+    #   * 0.0 suppresses all audio (no speech is transcribed).
+    #   * 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 Activity
+    #   Detection](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-input#detection).
+    # @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.
+    #
+    #   Specify a value in the range of 0.0 to 1.0:
+    #   * 0.0 (the default) provides no suppression (background audio suppression is
+    #   disabled).
+    #   * 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 [Speech Activity
+    #   Detection](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-input#detection).
+    # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def recognize_using_websocket(
       content_type: nil,
       recognize_callback:,
@@ -559,7 +625,9 @@ module IBMWatson
       processing_metrics_interval: nil,
       audio_metrics: nil,
       end_of_phrase_silence_time: nil,
-      split_transcript_at_phrase_end: nil
+      split_transcript_at_phrase_end: nil,
+      speech_detector_sensitivity: nil,
+      background_audio_suppression: nil
     )
       raise ArgumentError("Audio must be provided") if audio.nil? && !chunk_data
       raise ArgumentError("Recognize callback must be provided") if recognize_callback.nil?
@@ -568,6 +636,7 @@ module IBMWatson
       require_relative("./websocket/speech_to_text_websocket_listener.rb")
       headers = {}
       headers = conn.default_options.headers.to_hash unless conn.default_options.headers.to_hash.empty?
+      @authenticator.authenticate(headers)
       service_url = @service_url.gsub("https:", "wss:")
       params = {
         "model" => model,
@@ -598,7 +667,9 @@ module IBMWatson
         "processing_metrics_interval" => processing_metrics_interval,
         "audio_metrics" => audio_metrics,
         "end_of_phrase_silence_time" => end_of_phrase_silence_time,
-        "split_transcript_at_phrase_end" => split_transcript_at_phrase_end
+        "split_transcript_at_phrase_end" => split_transcript_at_phrase_end,
+        "speech_detector_sensitivity" => speech_detector_sensitivity,
+        "background_audio_suppression" => background_audio_suppression
       }
       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)
@@ -611,9 +682,9 @@ module IBMWatson
     # @!method register_callback(callback_url:, user_secret: nil)
     # Register a callback.
     # Registers a callback URL with the service for use with subsequent asynchronous
-    #   recognition requests. The service attempts to register, or white-list, the
-    #   callback URL if it is not already registered by sending a `GET` request to the
-    #   callback URL. The service passes a random alphanumeric challenge string via the
+    #   recognition requests. The service attempts to register, or allowlist, the callback
+    #   URL if it is not already registered by sending a `GET` request to the callback
+    #   URL. The service passes a random alphanumeric challenge string via the
     #   `challenge_string` parameter of the request. The request includes an `Accept`
     #   header that specifies `text/plain` as the required response type.
     #
@@ -625,9 +696,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 white-list
+    #   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 white-listed, the
+    #   callback** request. 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
@@ -645,7 +716,7 @@ module IBMWatson
     #   **See also:** [Registering a callback
     #   URL](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-async#register).
     # @param callback_url [String] An HTTP or HTTPS URL to which callback notifications are to be sent. To be
-    #   white-listed, the URL must successfully echo the challenge string during URL
+    #   allowlisted, the URL must successfully echo the challenge string during URL
     #   verification. During verification, the client can also check the signature that
     #   the service sends in the `X-Callback-Signature` header to verify the origin of the
     #   request.
@@ -683,7 +754,7 @@ module IBMWatson
     ##
     # @!method unregister_callback(callback_url:)
     # Unregister a callback.
-    # Unregisters a callback URL that was previously white-listed with a **Register a
+    # 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.
     #
@@ -716,7 +787,7 @@ module IBMWatson
     end
 
     ##
-    # @!method create_job(audio:, content_type: nil, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, processing_metrics: nil, processing_metrics_interval: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil)
+    # @!method create_job(audio:, content_type: nil, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, processing_metrics: nil, processing_metrics_interval: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil, speech_detector_sensitivity: nil, background_audio_suppression: nil)
     # Create a job.
     # Creates a job for a new asynchronous recognition request. The job is owned by the
     #   instance of the service whose credentials are used to create it. How you learn the
@@ -814,14 +885,14 @@ module IBMWatson
     #
     #    **See also:** [Audio
     #   formats](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-audio-formats#audio-formats).
-    # @param audio [String] The audio to transcribe.
+    # @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. See
     #   [Languages and
     #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models#models).
     # @param callback_url [String] A URL to which callback notifications are to be sent. The URL must already be
-    #   successfully white-listed by using the **Register a callback** method. You can
+    #   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.
     #
@@ -902,8 +973,14 @@ module IBMWatson
     # @param keywords [Array[String]] An array of keyword strings to spot in the audio. Each keyword string can include
     #   one or more string tokens. Keywords are spotted only in the final results, not in
     #   interim hypotheses. If you specify any keywords, you must also specify a keywords
-    #   threshold. You can spot a maximum of 1000 keywords. Omit the parameter or specify
-    #   an empty array if you do not need to spot keywords. See [Keyword
+    #   threshold. Omit the parameter or specify an empty array if you do not need to spot
+    #   keywords.
+    #
+    #   You can spot a maximum of 1000 keywords with a single request. A single keyword
+    #   can have a maximum length of 1024 characters, though the maximum effective length
+    #   for double-byte languages might be shorter. Keywords are case-insensitive.
+    #
+    #   See [Keyword
     #   spotting](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#keyword_spotting).
     # @param keywords_threshold [Float] A confidence value that is the lower bound for spotting a keyword. A word is
     #   considered to match a keyword if its confidence is greater than or equal to the
@@ -948,11 +1025,9 @@ module IBMWatson
     #   parameter to be `true`, regardless of whether you specify `false` for the
     #   parameter.
     #
-    #   **Note:** Applies to US English, Japanese, and Spanish (both broadband and
-    #   narrowband models) and UK English (narrowband model) transcription only. To
-    #   determine whether a language model supports speaker labels, you can also use the
-    #   **Get a model** method and check that the attribute `speaker_labels` is set to
-    #   `true`.
+    #   **Note:** Applies to US English, Australian English, German, Japanese, Korean, and
+    #   Spanish (both broadband and narrowband models) and UK English (narrowband model)
+    #   transcription only.
     #
     #   See [Speaker
     #   labels](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#speaker_labels).
@@ -1035,8 +1110,33 @@ module IBMWatson
     #
     #   See [Split transcript at phrase
     #   end](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-output#split_transcript).
+    # @param speech_detector_sensitivity [Float] The sensitivity of speech activity detection that the service is to perform. Use
+    #   the parameter to suppress word insertions from music, coughing, and other
+    #   non-speech events. The service biases the audio it passes for speech recognition
+    #   by evaluating the input audio against prior models of speech and non-speech
+    #   activity.
+    #
+    #   Specify a value between 0.0 and 1.0:
+    #   * 0.0 suppresses all audio (no speech is transcribed).
+    #   * 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 Activity
+    #   Detection](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-input#detection).
+    # @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.
+    #
+    #   Specify a value in the range of 0.0 to 1.0:
+    #   * 0.0 (the default) provides no suppression (background audio suppression is
+    #   disabled).
+    #   * 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 [Speech Activity
+    #   Detection](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-input#detection).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
-    def create_job(audio:, content_type: nil, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, processing_metrics: nil, processing_metrics_interval: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil)
+    def create_job(audio:, content_type: nil, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, language_customization_id: nil, acoustic_customization_id: nil, base_model_version: nil, customization_weight: nil, inactivity_timeout: nil, keywords: nil, keywords_threshold: nil, max_alternatives: nil, word_alternatives_threshold: nil, word_confidence: nil, timestamps: nil, profanity_filter: nil, smart_formatting: nil, speaker_labels: nil, customization_id: nil, grammar_name: nil, redaction: nil, processing_metrics: nil, processing_metrics_interval: nil, audio_metrics: nil, end_of_phrase_silence_time: nil, split_transcript_at_phrase_end: nil, speech_detector_sensitivity: nil, background_audio_suppression: nil)
       raise ArgumentError.new("audio must be provided") if audio.nil?
 
       headers = {
@@ -1073,7 +1173,9 @@ module IBMWatson
         "processing_metrics_interval" => processing_metrics_interval,
         "audio_metrics" => audio_metrics,
         "end_of_phrase_silence_time" => end_of_phrase_silence_time,
-        "split_transcript_at_phrase_end" => split_transcript_at_phrase_end
+        "split_transcript_at_phrase_end" => split_transcript_at_phrase_end,
+        "speech_detector_sensitivity" => speech_detector_sensitivity,
+        "background_audio_suppression" => background_audio_suppression
       }
 
       data = audio
@@ -1290,8 +1392,12 @@ module IBMWatson
     #   **See also:** [Listing custom language
     #   models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModels#listModels-language).
     # @param language [String] The identifier of the language for which custom language or custom acoustic models
-    #   are to be returned (for example, `en-US`). Omit the parameter to see all custom
-    #   language or custom acoustic models that are owned by the requesting credentials.
+    #   are to be returned. Omit the parameter to see all custom language or custom
+    #   acoustic models that are owned by the requesting credentials.
+    #
+    #   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).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_language_models(language: nil)
       headers = {
@@ -1599,18 +1705,20 @@ module IBMWatson
     #
     #   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 can take on the order of a minute or two 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
+    #   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 are referred to as
-    #   out-of-vocabulary (OOV) words. 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.
+    #   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.
     #
     #   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
@@ -1627,10 +1735,12 @@ module IBMWatson
     #   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)
-    #   * [Add a corpus to the custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#addCorpus).
+    #   * [Validating a words
+    #   resource](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel).
     # @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.
@@ -1859,7 +1969,10 @@ module IBMWatson
     #   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.
+    #   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.
     #   * 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
@@ -1889,10 +2002,12 @@ module IBMWatson
     #
     #
     #   **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)
-    #   * [Add words to the custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#addWords).
+    #   * [Validating a words
+    #   resource](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel).
     # @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.
@@ -1948,7 +2063,10 @@ module IBMWatson
     #   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.
+    #   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.
     #   * 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
@@ -1960,10 +2078,12 @@ module IBMWatson
     #   the **List a custom word** 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)
-    #   * [Add words to the custom language
-    #   model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreate#addWords).
+    #   * [Validating a words
+    #   resource](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-corporaWords#validateModel).
     # @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.
@@ -2147,12 +2267,12 @@ module IBMWatson
     #
     #   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
-    #   extracts new words that it finds. This can take a few seconds 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.
+    #   extracts new words that it finds. This operation can take a few seconds or minutes
+    #   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
@@ -2396,8 +2516,12 @@ module IBMWatson
     #   **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 (for example, `en-US`). Omit the parameter to see all custom
-    #   language or custom acoustic models that are owned by the requesting credentials.
+    #   are to be returned. Omit the parameter to see all custom language or custom
+    #   acoustic models that are owned by the requesting credentials.
+    #
+    #   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).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_acoustic_models(language: nil)
       headers = {
@@ -2495,14 +2619,14 @@ module IBMWatson
     #   it. You must use credentials for the instance of the service that owns a model to
     #   train it.
     #
-    #   The training method is asynchronous. It can take on the order of minutes or hours
-    #   to complete depending on the total amount of audio data on which the custom
-    #   acoustic model is being trained and the current load on the service. Typically,
-    #   training a custom acoustic model takes approximately two to four times the length
-    #   of its audio data. The range of time depends on the model being trained and the
-    #   nature of the audio, such as whether the audio is clean or noisy. The method
-    #   returns an HTTP 200 response code to indicate that the training process has begun.
-    #
+    #   The training method is asynchronous. Training time depends on the cumulative
+    #   amount of audio data that the custom acoustic model contains and the current load
+    #   on the service. When you train or retrain a model, the service uses all of the
+    #   model's audio data in the training. Training a custom acoustic model takes
+    #   approximately as long as the length of its cumulative audio data. For example, it
+    #   takes approximately 2 hours to train a model that contains a total of 2 hours of
+    #   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
@@ -2518,8 +2642,9 @@ module IBMWatson
     #   Train with a custom language model if you have verbatim transcriptions of the
     #   audio files that you have added to the custom model or you have either corpora
     #   (text files) or a list of words that are relevant to the contents of the audio
-    #   files. Both of the custom models must be based on the same version of the same
-    #   base model for training to succeed.
+    #   files. For training to succeed, both of the custom models must be based on the
+    #   same version of the same base model, and the custom language model must be fully
+    #   trained and available.
     #
     #   **See also:**
     #   * [Train the custom acoustic
@@ -2535,6 +2660,9 @@ module IBMWatson
     #   another training request or a request to add audio resources to the model.
     #   * The custom model contains less than 10 minutes or more than 200 hours of audio
     #   data.
+    #   * You passed a custom language model with the `custom_language_model_id` query
+    #   parameter that is not in the available state. A custom language model must be
+    #   fully trained and available to be used to train a custom acoustic model.
     #   * You passed an incompatible custom language model with the
     #   `custom_language_model_id` query parameter. Both custom models must be based on
     #   the same version of the same base model.
@@ -2550,8 +2678,8 @@ module IBMWatson
     #   been trained with verbatim transcriptions of the audio resources or that contains
     #   words that are relevant to the contents of the audio resources. The custom
     #   language model must be based on the same version of the same base model as the
-    #   custom acoustic model. The credentials specified with the request must own both
-    #   custom models.
+    #   custom acoustic model, and the custom language model must be fully trained and
+    #   available. The credentials specified with the request must own both custom models.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def train_acoustic_model(customization_id:, custom_language_model_id: nil)
       raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
@@ -2649,8 +2777,9 @@ module IBMWatson
     #   service that owns the custom model.
     # @param custom_language_model_id [String] If the custom acoustic model was trained with a custom language model, the
     #   customization ID (GUID) of that custom language model. The custom language model
-    #   must be upgraded before the custom acoustic model can be upgraded. The credentials
-    #   specified with the request must own both custom models.
+    #   must be upgraded before the custom acoustic model can be upgraded. The custom
+    #   language model must be fully trained and available. The credentials specified with
+    #   the request must own both custom models.
     # @param force [Boolean] If `true`, forces the upgrade of a custom acoustic model for which no input data
     #   has been modified since it was last trained. Use this parameter only to force the
     #   upgrade of a custom acoustic model that is trained with a custom language model,
@@ -2745,14 +2874,14 @@ module IBMWatson
     #   same name as an existing audio resource, set the `allow_overwrite` parameter to
     #   `true`; otherwise, the request fails.
     #
-    #   The method is asynchronous. It can take several seconds to complete depending on
-    #   the duration of the audio and, in the case of an archive file, the total number of
-    #   audio files being processed. The service returns a 201 response code if the audio
-    #   is valid. It then asynchronously analyzes the contents of the audio file or files
-    #   and automatically extracts information about the audio such as its length,
-    #   sampling rate, and encoding. You cannot submit requests to train or upgrade the
-    #   model until the service's analysis of all audio resources for current requests
-    #   completes.
+    #   The method is asynchronous. It can take several seconds or minutes to complete
+    #   depending on the duration of the audio and, in the case of an archive file, the
+    #   total number of audio files being processed. The service returns a 201 response
+    #   code if the audio is valid. It then asynchronously analyzes the contents of the
+    #   audio file or files and automatically extracts information about the audio such as
+    #   its length, sampling rate, and encoding. You cannot submit requests to train or
+    #   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
@@ -2841,7 +2970,7 @@ module IBMWatson
     #   used, their use is strongly discouraged.)
     #   * Do not use the name of an audio resource that has already been added to the
     #   custom model.
-    # @param audio_resource [String] The audio resource that is to be added to the custom acoustic model, an individual
+    # @param audio_resource [File] The audio resource that is to be added to the custom acoustic model, an individual
     #   audio file or an archive file.
     #
     #   With the `curl` command, use the `--data-binary` option to upload the file for the
@@ -3009,10 +3138,15 @@ module IBMWatson
     #   deletes all data for the customer ID, regardless of the method by which the
     #   information was added. The method has no effect if no data is associated with the
     #   customer ID. You must issue the request with credentials for the same instance of
-    #   the service that was used to associate the customer ID with the data.
-    #
-    #   You associate a customer ID with data by passing the `X-Watson-Metadata` header
-    #   with a request that passes the data.
+    #   the service that was used to associate the customer ID with the data. You
+    #   associate a customer ID with data by passing the `X-Watson-Metadata` header with a
+    #   request that passes the data.
+    #
+    #   **Note:** If you delete an instance of the service from the service console, all
+    #   data associated with that service instance is automatically deleted. This includes
+    #   all custom language models, corpora, grammars, and words; all custom acoustic
+    #   models and audio resources; all registered endpoints for the asynchronous HTTP
+    #   interface; and all data related to speech recognition requests.
     #
     #   **See also:** [Information
     #   security](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-information-security#information-security).