ibm_watson 1.2.0 → 1.6.0

data/lib/ibm_watson/text_to_speech_v1.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# (C) Copyright IBM Corp. 2020.
+# (C) Copyright IBM Corp. 2018, 2020.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,23 +14,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# The IBM® Text to Speech service provides APIs that use IBM's speech-synthesis
-# capabilities to synthesize text into natural-sounding speech in a variety of languages,
-# dialects, and voices. The service supports at least one male or female voice, sometimes
-# both, for each language. The audio is streamed back to the client with minimal delay.
+# The IBM Watson™ Text to Speech service provides APIs that use IBM's
+# speech-synthesis capabilities to synthesize text into natural-sounding speech in a
+# variety of languages, dialects, and voices. The service supports at least one male or
+# female voice, sometimes both, for each language. The audio is streamed back to the
+# client with minimal delay.
 #
 # For speech synthesis, the service supports a synchronous HTTP Representational State
-# Transfer (REST) interface. It also supports a WebSocket interface that provides both
-# plain text and SSML input, including the SSML <mark> element and word timings.
-# SSML is an XML-based markup language that provides text annotation for speech-synthesis
-# applications.
+# Transfer (REST) interface and a WebSocket interface. Both interfaces support plain text
+# and SSML input. SSML is an XML-based markup language that provides text annotation for
+# speech-synthesis applications. The WebSocket interface also supports the SSML
+# <code>&lt;mark&gt;</code> element and word timings.
 #
-# The service also offers a customization interface. You can use the interface to define
-# sounds-like or phonetic translations for words. A sounds-like translation consists of
-# one or more words that, when combined, sound like the word. A phonetic translation is
-# based on the SSML phoneme format for representing a word. You can specify a phonetic
-# translation in standard International Phonetic Alphabet (IPA) representation or in the
-# proprietary IBM Symbolic Phonetic Representation (SPR).
+# The service offers a customization interface that you can use to define sounds-like or
+# phonetic translations for words. A sounds-like translation consists of one or more words
+# that, when combined, sound like the word. A phonetic translation is based on the SSML
+# phoneme format for representing a word. You can specify a phonetic translation in
+# standard International Phonetic Alphabet (IPA) representation or in the proprietary IBM
+# Symbolic Phonetic Representation (SPR). The Arabic, Chinese, Dutch, and Korean languages
+# support only IPA.
 
 require "concurrent"
 require "erb"
@@ -44,6 +46,8 @@ module IBMWatson
   # The Text to Speech V1 service.
   class TextToSpeechV1 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "text_to_speech"
+    DEFAULT_SERVICE_URL = "https://api.us-south.text-to-speech.watson.cloud.ibm.com"
     ##
     # @!method initialize(args)
     # Construct a new client for the Text to Speech service.
@@ -52,15 +56,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/text-to-speech/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] = "text_to_speech"
       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
 
     #########################
@@ -71,11 +79,13 @@ module IBMWatson
     # @!method list_voices
     # List voices.
     # Lists all voices available for use with the service. The information includes the
-    #   name, language, gender, and other details about the voice. To see information
-    #   about a specific voice, use the **Get a voice** method.
+    #   name, language, gender, and other details about the voice. The ordering of the
+    #   list of voices can change from call to call; do not rely on an alphabetized or
+    #   static list of voices. To see information about a specific voice, use the **Get a
+    #   voice** method.
     #
     #   **See also:** [Listing all available
-    #   voices](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-voices#listVoices).
+    #   voices](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-voices#listVoices).
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_voices
       headers = {
@@ -104,7 +114,7 @@ module IBMWatson
     #   **List voices** method.
     #
     #   **See also:** [Listing a specific
-    #   voice](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-voices#listVoice).
+    #   voice](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-voices#listVoice).
     # @param voice [String] The voice for which information is to be returned.
     # @param customization_id [String] The customization ID (GUID) of a custom voice model for which information is to be
     #   returned. You must make the request with credentials for the instance of the
@@ -150,7 +160,7 @@ module IBMWatson
     #   specify. The service returns the synthesized audio stream as an array of bytes.
     #
     #   **See also:** [The HTTP
-    #   interface](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-usingHTTP#usingHTTP).
+    #   interface](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-usingHTTP#usingHTTP).
     #
     #
     #   ### Audio formats (accept types)
@@ -198,7 +208,7 @@ module IBMWatson
     #
     #   For more information about specifying an audio format, including additional
     #   details about some of the formats, see [Audio
-    #   formats](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-audioFormats#audioFormats).
+    #   formats](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-audioFormats#audioFormats).
     #
     #
     #   ### Warning messages
@@ -216,10 +226,10 @@ module IBMWatson
     #   description.
     # @param voice [String] The voice to use for synthesis.
     # @param customization_id [String] The customization ID (GUID) of a custom voice model to use for the synthesis. If a
-    #   custom voice model is specified, it is guaranteed to work only if it matches the
-    #   language of the indicated voice. You must make the request with credentials for
-    #   the instance of the service that owns the custom model. Omit the parameter to use
-    #   the specified voice with no customization.
+    #   custom voice model is specified, it works only if it matches the language of the
+    #   indicated voice. You must make the request with credentials for the instance of
+    #   the service that owns the custom model. Omit the parameter to use the specified
+    #   voice with no customization.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def synthesize(text:, accept: nil, voice: nil, customization_id: nil)
       raise ArgumentError.new("text must be provided") if text.nil?
@@ -263,17 +273,17 @@ module IBMWatson
     #   specific voice to see the default translation for the language of that voice or
     #   for a specific custom voice model to see the translation for that voice model.
     #
-    #   **Note:** This method is currently a beta release. The method does not support the
-    #   Arabic, Chinese, and Dutch languages.
+    #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Querying a word from a
-    #   language](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuWordsQueryLanguage).
+    #   language](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuWordsQueryLanguage).
     # @param text [String] The word for which the pronunciation is requested.
     # @param voice [String] A voice that specifies the language in which the pronunciation is to be returned.
     #   All voices for the same language (for example, `en-US`) return the same
     #   translation.
-    # @param format [String] The phoneme format in which to return the pronunciation. Omit the parameter to
-    #   obtain the pronunciation in the default format.
+    # @param format [String] The phoneme format in which to return the pronunciation. The Arabic, Chinese,
+    #   Dutch, and Korean languages support only IPA. Omit the parameter to obtain the
+    #   pronunciation in the default format.
     # @param customization_id [String] The customization ID (GUID) of a custom voice model for which the pronunciation is
     #   to be returned. The language of a specified custom model must match the language
     #   of the specified voice. If the word is not defined in the specified custom model,
@@ -320,14 +330,15 @@ module IBMWatson
     #   model. The model is owned by the instance of the service whose credentials are
     #   used to create it.
     #
-    #   **Note:** This method is currently a beta release. The service does not support
-    #   voice model customization for the Arabic, Chinese, and Dutch languages.
+    #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Creating a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customModels#cuModelsCreate).
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customModels#cuModelsCreate).
     # @param name [String] The name of the new custom voice model.
-    # @param language [String] The language of the new custom voice model. Omit the parameter to use the the
-    #   default language, `en-US`.
+    # @param language [String] The language of the new custom voice model. You create a custom voice model for a
+    #   specific language, not for a specific voice. A custom model can be used with any
+    #   voice, standard or neural, for its specified language. Omit the parameter to use
+    #   the the default language, `en-US`.
     # @param description [String] A description of the new custom voice model. Specifying a description is
     #   recommended.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
@@ -370,7 +381,7 @@ module IBMWatson
     #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Querying all custom
-    #   models](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customModels#cuModelsQueryAll).
+    #   models](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customModels#cuModelsQueryAll).
     # @param language [String] The language for which custom voice models that are owned by the requesting
     #   credentials are to be returned. Omit the parameter to see all custom voice models
     #   that are owned by the requester.
@@ -425,11 +436,11 @@ module IBMWatson
     #
     #   **See also:**
     #   * [Updating a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customModels#cuModelsUpdate)
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customModels#cuModelsUpdate)
     #   * [Adding words to a Japanese custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuJapaneseAdd)
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuJapaneseAdd)
     #   * [Understanding
-    #   customization](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customIntro#customIntro).
+    #   customization](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customIntro#customIntro).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @param name [String] A new name for the custom voice model.
@@ -475,7 +486,7 @@ module IBMWatson
     #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Querying a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customModels#cuModelsQuery).
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customModels#cuModelsQuery).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
@@ -507,7 +518,7 @@ module IBMWatson
     #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Deleting a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customModels#cuModelsDelete).
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customModels#cuModelsDelete).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @return [nil]
@@ -560,11 +571,11 @@ module IBMWatson
     #
     #   **See also:**
     #   * [Adding multiple words to a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuWordsAdd)
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuWordsAdd)
     #   * [Adding words to a Japanese custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuJapaneseAdd)
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuJapaneseAdd)
     #   * [Understanding
-    #   customization](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customIntro#customIntro).
+    #   customization](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customIntro#customIntro).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @param words [Array[Word]] The **Add custom words** method accepts an array of `Word` objects. Each object
@@ -613,7 +624,7 @@ module IBMWatson
     #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Querying all words from a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuWordsQueryModel).
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuWordsQueryModel).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
@@ -663,24 +674,25 @@ module IBMWatson
     #
     #   **See also:**
     #   * [Adding a single word to a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuWordAdd)
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuWordAdd)
     #   * [Adding words to a Japanese custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuJapaneseAdd)
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuJapaneseAdd)
     #   * [Understanding
-    #   customization](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customIntro#customIntro).
+    #   customization](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customIntro#customIntro).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @param word [String] The word that is to be added or updated for the custom voice model.
     # @param translation [String] The phonetic or sounds-like translation for the word. A phonetic translation is
     #   based on the SSML format for representing the phonetic string of a word either as
-    #   an IPA translation or as an IBM SPR translation. A sounds-like is one or more
-    #   words that, when combined, sound like the word.
+    #   an IPA translation or as an IBM SPR translation. The Arabic, Chinese, Dutch, and
+    #   Korean languages support only IPA. A sounds-like is one or more words that, when
+    #   combined, sound like the word.
     # @param part_of_speech [String] **Japanese only.** The part of speech for the word. The service uses the value to
     #   produce the correct intonation for the word. You can create only a single entry,
     #   with or without a single part of speech, for any word; you cannot create multiple
     #   entries with different parts of speech for the same word. For more information,
     #   see [Working with Japanese
-    #   entries](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-rules#jaNotes).
+    #   entries](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-rules#jaNotes).
     # @return [nil]
     def add_word(customization_id:, word:, translation:, part_of_speech: nil)
       raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
@@ -721,7 +733,7 @@ module IBMWatson
     #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Querying a single word from a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuWordQueryModel).
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuWordQueryModel).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @param word [String] The word that is to be queried from the custom voice model.
@@ -757,7 +769,7 @@ module IBMWatson
     #   **Note:** This method is currently a beta release.
     #
     #   **See also:** [Deleting a word from a custom
-    #   model](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-customWords#cuWordDelete).
+    #   model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWords#cuWordDelete).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with credentials for the instance of the service that owns the custom model.
     # @param word [String] The word that is to be deleted from the custom voice model.
@@ -793,13 +805,17 @@ 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.
+    #   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.
     #
-    #   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 voice models and word/translation pairs, and all data related to speech
+    #   synthesis requests.
     #
     #   **See also:** [Information
-    #   security](https://cloud.ibm.com/docs/services/text-to-speech?topic=text-to-speech-information-security#information-security).
+    #   security](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-information-security#information-security).
     # @param customer_id [String] The customer ID for which all data is to be deleted.
     # @return [nil]
     def delete_user_data(customer_id:)

data/lib/ibm_watson/tone_analyzer_v3.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# (C) Copyright IBM Corp. 2020.
+# (C) Copyright IBM Corp. 2018, 2020.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -38,6 +38,8 @@ module IBMWatson
   # The Tone Analyzer V3 service.
   class ToneAnalyzerV3 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "tone_analyzer"
+    DEFAULT_SERVICE_URL = "https://api.us-south.tone-analyzer.watson.cloud.ibm.com"
     ##
     # @!method initialize(args)
     # Construct a new client for the Tone Analyzer service.
@@ -56,19 +58,23 @@ 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[:version] = nil
-      defaults[:service_url] = "https://gateway.watsonplatform.net/tone-analyzer/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)
       @version = args[:version]
       raise ArgumentError.new("version must be provided") if @version.nil?
 
-      args[:service_name] = "tone_analyzer"
       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
 
     #########################
@@ -97,7 +103,7 @@ module IBMWatson
     #   analyzes only the textual content.
     #
     #   **See also:** [Using the general-purpose
-    #   endpoint](https://cloud.ibm.com/docs/services/tone-analyzer?topic=tone-analyzer-utgpe#utgpe).
+    #   endpoint](https://cloud.ibm.com/docs/tone-analyzer?topic=tone-analyzer-utgpe#utgpe).
     # @param tone_input [ToneInput] JSON, plain text, or HTML input that contains the content to be analyzed. For JSON
     #   input, provide an object of type `ToneInput`.
     # @param content_type [String] The type of the input. A character encoding can be specified by including a
@@ -177,7 +183,7 @@ module IBMWatson
     #   character encoding for JSON content is effectively always UTF-8.
     #
     #   **See also:** [Using the customer-engagement
-    #   endpoint](https://cloud.ibm.com/docs/services/tone-analyzer?topic=tone-analyzer-utco#utco).
+    #   endpoint](https://cloud.ibm.com/docs/tone-analyzer?topic=tone-analyzer-utco#utco).
     # @param utterances [Array[Utterance]] An array of `Utterance` objects that provides the input content that the service
     #   is to analyze.
     # @param content_language [String] The language of the input text for the request: English or French. Regional

data/lib/ibm_watson/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IBMWatson
-  VERSION = "1.2.0"
+  VERSION = "1.6.0"
 end

data/lib/ibm_watson/visual_recognition_v3.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# (C) Copyright IBM Corp. 2020.
+# (C) Copyright IBM Corp. 2018, 2020.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -30,6 +30,8 @@ module IBMWatson
   # The Visual Recognition V3 service.
   class VisualRecognitionV3 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "visual_recognition"
+    DEFAULT_SERVICE_URL = "https://api.us-south.visual-recognition.watson.cloud.ibm.com"
     ##
     # @!method initialize(args)
     # Construct a new client for the Visual Recognition service.
@@ -48,19 +50,23 @@ 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[:version] = nil
-      defaults[:service_url] = "https://gateway.watsonplatform.net/visual-recognition/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)
       @version = args[:version]
       raise ArgumentError.new("version must be provided") if @version.nil?
 
-      args[:service_name] = "visual_recognition"
       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
 
     #########################
@@ -305,7 +311,7 @@ module IBMWatson
     # Update a custom classifier by adding new positive or negative classes or by adding
     #   new images to existing classes. You must supply at least one set of positive or
     #   negative examples. For details, see [Updating custom
-    #   classifiers](https://cloud.ibm.com/docs/services/visual-recognition?topic=visual-recognition-customizing#updating-custom-classifiers).
+    #   classifiers](https://cloud.ibm.com/docs/visual-recognition?topic=visual-recognition-customizing#updating-custom-classifiers).
     #
     #   Encode all names in UTF-8 if they contain non-ASCII characters (.zip and image
     #   file names, and classifier and class names). The service assumes UTF-8 encoding if
@@ -464,7 +470,7 @@ module IBMWatson
     #   You associate a customer ID with data by passing the `X-Watson-Metadata` header
     #   with a request that passes data. For more information about personal data and
     #   customer IDs, see [Information
-    #   security](https://cloud.ibm.com/docs/services/visual-recognition?topic=visual-recognition-information-security).
+    #   security](https://cloud.ibm.com/docs/visual-recognition?topic=visual-recognition-information-security).
     # @param customer_id [String] The customer ID for which all data is to be deleted.
     # @return [nil]
     def delete_user_data(customer_id:)

data/lib/ibm_watson/visual_recognition_v4.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# (C) Copyright IBM Corp. 2020.
+# (C) Copyright IBM Corp. 2019, 2020.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -29,6 +29,8 @@ module IBMWatson
   # The Visual Recognition V4 service.
   class VisualRecognitionV4 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "visual_recognition"
+    DEFAULT_SERVICE_URL = "https://api.us-south.visual-recognition.watson.cloud.ibm.com"
     ##
     # @!method initialize(args)
     # Construct a new client for the Visual Recognition service.
@@ -47,19 +49,23 @@ 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[:version] = nil
-      defaults[:service_url] = "https://gateway.watsonplatform.net/visual-recognition/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)
       @version = args[:version]
       raise ArgumentError.new("version must be provided") if @version.nil?
 
-      args[:service_name] = "visual_recognition"
       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
 
     #########################
@@ -319,6 +325,51 @@ module IBMWatson
       )
       nil
     end
+
+    ##
+    # @!method get_model_file(collection_id:, feature:, model_format:)
+    # Get a model.
+    # Download a model that you can deploy to detect objects in images. The collection
+    #   must include a generated model, which is indicated in the response for the
+    #   collection details as `"rscnn_ready": true`. If the value is `false`, train or
+    #   retrain the collection to generate the model.
+    #
+    #   Currently, the model format is specific to Android apps. For more information
+    #   about how to deploy the model to your app, see the [Watson Visual Recognition on
+    #   Android](https://github.com/matt-ny/rscnn) project in GitHub.
+    # @param collection_id [String] The identifier of the collection.
+    # @param feature [String] The feature for the model.
+    # @param model_format [String] The format of the returned model.
+    # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
+    def get_model_file(collection_id:, feature:, model_format:)
+      raise ArgumentError.new("collection_id must be provided") if collection_id.nil?
+
+      raise ArgumentError.new("feature must be provided") if feature.nil?
+
+      raise ArgumentError.new("model_format must be provided") if model_format.nil?
+
+      headers = {
+      }
+      sdk_headers = Common.new.get_sdk_headers("watson_vision_combined", "V4", "get_model_file")
+      headers.merge!(sdk_headers)
+
+      params = {
+        "version" => @version,
+        "feature" => feature,
+        "model_format" => model_format
+      }
+
+      method_url = "/v4/collections/%s/model" % [ERB::Util.url_encode(collection_id)]
+
+      response = request(
+        method: "GET",
+        url: method_url,
+        headers: headers,
+        params: params,
+        accept_json: false
+      )
+      response
+    end
     #########################
     # Images
     #########################
@@ -529,6 +580,150 @@ module IBMWatson
       response
     end
     #########################
+    # Objects
+    #########################
+
+    ##
+    # @!method list_object_metadata(collection_id:)
+    # List object metadata.
+    # Retrieves a list of object names in a collection.
+    # @param collection_id [String] The identifier of the collection.
+    # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
+    def list_object_metadata(collection_id:)
+      raise ArgumentError.new("collection_id must be provided") if collection_id.nil?
+
+      headers = {
+      }
+      sdk_headers = Common.new.get_sdk_headers("watson_vision_combined", "V4", "list_object_metadata")
+      headers.merge!(sdk_headers)
+
+      params = {
+        "version" => @version
+      }
+
+      method_url = "/v4/collections/%s/objects" % [ERB::Util.url_encode(collection_id)]
+
+      response = request(
+        method: "GET",
+        url: method_url,
+        headers: headers,
+        params: params,
+        accept_json: true
+      )
+      response
+    end
+
+    ##
+    # @!method update_object_metadata(collection_id:, object:, new_object:)
+    # Update an object name.
+    # Update the name of an object. A successful request updates the training data for
+    #   all images that use the object.
+    # @param collection_id [String] The identifier of the collection.
+    # @param object [String] The name of the object.
+    # @param new_object [String] The updated name of the object. The name can contain alphanumeric, underscore,
+    #   hyphen, space, and dot characters. It cannot begin with the reserved prefix
+    #   `sys-`.
+    # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
+    def update_object_metadata(collection_id:, object:, new_object:)
+      raise ArgumentError.new("collection_id must be provided") if collection_id.nil?
+
+      raise ArgumentError.new("object must be provided") if object.nil?
+
+      raise ArgumentError.new("new_object must be provided") if new_object.nil?
+
+      headers = {
+      }
+      sdk_headers = Common.new.get_sdk_headers("watson_vision_combined", "V4", "update_object_metadata")
+      headers.merge!(sdk_headers)
+
+      params = {
+        "version" => @version
+      }
+
+      data = {
+        "object" => new_object
+      }
+
+      method_url = "/v4/collections/%s/objects/%s" % [ERB::Util.url_encode(collection_id), ERB::Util.url_encode(object)]
+
+      response = request(
+        method: "POST",
+        url: method_url,
+        headers: headers,
+        params: params,
+        json: data,
+        accept_json: true
+      )
+      response
+    end
+
+    ##
+    # @!method get_object_metadata(collection_id:, object:)
+    # Get object metadata.
+    # Get the number of bounding boxes for a single object in a collection.
+    # @param collection_id [String] The identifier of the collection.
+    # @param object [String] The name of the object.
+    # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
+    def get_object_metadata(collection_id:, object:)
+      raise ArgumentError.new("collection_id must be provided") if collection_id.nil?
+
+      raise ArgumentError.new("object must be provided") if object.nil?
+
+      headers = {
+      }
+      sdk_headers = Common.new.get_sdk_headers("watson_vision_combined", "V4", "get_object_metadata")
+      headers.merge!(sdk_headers)
+
+      params = {
+        "version" => @version
+      }
+
+      method_url = "/v4/collections/%s/objects/%s" % [ERB::Util.url_encode(collection_id), ERB::Util.url_encode(object)]
+
+      response = request(
+        method: "GET",
+        url: method_url,
+        headers: headers,
+        params: params,
+        accept_json: true
+      )
+      response
+    end
+
+    ##
+    # @!method delete_object(collection_id:, object:)
+    # Delete an object.
+    # Delete one object from a collection. A successful request deletes the training
+    #   data from all images that use the object.
+    # @param collection_id [String] The identifier of the collection.
+    # @param object [String] The name of the object.
+    # @return [nil]
+    def delete_object(collection_id:, object:)
+      raise ArgumentError.new("collection_id must be provided") if collection_id.nil?
+
+      raise ArgumentError.new("object must be provided") if object.nil?
+
+      headers = {
+      }
+      sdk_headers = Common.new.get_sdk_headers("watson_vision_combined", "V4", "delete_object")
+      headers.merge!(sdk_headers)
+
+      params = {
+        "version" => @version
+      }
+
+      method_url = "/v4/collections/%s/objects/%s" % [ERB::Util.url_encode(collection_id), ERB::Util.url_encode(object)]
+
+      request(
+        method: "DELETE",
+        url: method_url,
+        headers: headers,
+        params: params,
+        accept_json: true
+      )
+      nil
+    end
+    #########################
     # Training
     #########################
 
@@ -660,7 +855,7 @@ module IBMWatson
     #   You associate a customer ID with data by passing the `X-Watson-Metadata` header
     #   with a request that passes data. For more information about personal data and
     #   customer IDs, see [Information
-    #   security](https://cloud.ibm.com/docs/services/visual-recognition?topic=visual-recognition-information-security).
+    #   security](https://cloud.ibm.com/docs/visual-recognition?topic=visual-recognition-information-security).
     # @param customer_id [String] The customer ID for which all data is to be deleted.
     # @return [nil]
     def delete_user_data(customer_id:)