ibm_watson 0.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (48) hide show
  1. checksums.yaml +7 -0
  2. data/README.md +258 -0
  3. data/bin/console +14 -0
  4. data/bin/setup +8 -0
  5. data/lib/ibm_watson.rb +16 -0
  6. data/lib/ibm_watson/assistant_v1.rb +1997 -0
  7. data/lib/ibm_watson/detailed_response.rb +21 -0
  8. data/lib/ibm_watson/discovery_v1.rb +2039 -0
  9. data/lib/ibm_watson/iam_token_manager.rb +166 -0
  10. data/lib/ibm_watson/language_translator_v3.rb +411 -0
  11. data/lib/ibm_watson/natural_language_classifier_v1.rb +309 -0
  12. data/lib/ibm_watson/natural_language_understanding_v1.rb +297 -0
  13. data/lib/ibm_watson/personality_insights_v3.rb +260 -0
  14. data/lib/ibm_watson/speech_to_text_v1.rb +2153 -0
  15. data/lib/ibm_watson/text_to_speech_v1.rb +716 -0
  16. data/lib/ibm_watson/tone_analyzer_v3.rb +287 -0
  17. data/lib/ibm_watson/version.rb +3 -0
  18. data/lib/ibm_watson/visual_recognition_v3.rb +579 -0
  19. data/lib/ibm_watson/watson_api_exception.rb +41 -0
  20. data/lib/ibm_watson/watson_service.rb +180 -0
  21. data/lib/ibm_watson/websocket/recognize_callback.rb +32 -0
  22. data/lib/ibm_watson/websocket/speech_to_text_websocket_listener.rb +162 -0
  23. data/rakefile +45 -0
  24. data/test/integration/test_assistant_v1.rb +645 -0
  25. data/test/integration/test_discovery_v1.rb +200 -0
  26. data/test/integration/test_iam_assistant_v1.rb +707 -0
  27. data/test/integration/test_language_translator_v3.rb +81 -0
  28. data/test/integration/test_natural_language_classifier_v1.rb +69 -0
  29. data/test/integration/test_natural_language_understanding_v1.rb +98 -0
  30. data/test/integration/test_personality_insights_v3.rb +95 -0
  31. data/test/integration/test_speech_to_text_v1.rb +187 -0
  32. data/test/integration/test_text_to_speech_v1.rb +81 -0
  33. data/test/integration/test_tone_analyzer_v3.rb +72 -0
  34. data/test/integration/test_visual_recognition_v3.rb +64 -0
  35. data/test/test_helper.rb +22 -0
  36. data/test/unit/test_assistant_v1.rb +1598 -0
  37. data/test/unit/test_discovery_v1.rb +1144 -0
  38. data/test/unit/test_iam_token_manager.rb +165 -0
  39. data/test/unit/test_language_translator_v3.rb +461 -0
  40. data/test/unit/test_natural_language_classifier_v1.rb +187 -0
  41. data/test/unit/test_natural_language_understanding_v1.rb +132 -0
  42. data/test/unit/test_personality_insights_v3.rb +172 -0
  43. data/test/unit/test_speech_to_text_v1.rb +755 -0
  44. data/test/unit/test_text_to_speech_v1.rb +336 -0
  45. data/test/unit/test_tone_analyzer_v3.rb +200 -0
  46. data/test/unit/test_vcap_using_personality_insights.rb +150 -0
  47. data/test/unit/test_visual_recognition_v3.rb +345 -0
  48. metadata +302 -0
@@ -0,0 +1,260 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2018 IBM All Rights Reserved.
4
+ #
5
+ # Licensed under the Apache License, Version 2.0 (the "License");
6
+ # you may not use this file except in compliance with the License.
7
+ # You may obtain a copy of the License at
8
+ #
9
+ # http://www.apache.org/licenses/LICENSE-2.0
10
+ #
11
+ # Unless required by applicable law or agreed to in writing, software
12
+ # distributed under the License is distributed on an "AS IS" BASIS,
13
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ # See the License for the specific language governing permissions and
15
+ # limitations under the License.
16
+
17
+ # The IBM Watson™ Personality Insights service enables applications to derive
18
+ # insights from social media, enterprise data, or other digital communications. The
19
+ # service uses linguistic analytics to infer individuals' intrinsic personality
20
+ # characteristics, including Big Five, Needs, and Values, from digital communications such
21
+ # as email, text messages, tweets, and forum posts.
22
+ #
23
+ # The service can automatically infer, from potentially noisy social media, portraits of
24
+ # individuals that reflect their personality characteristics. The service can infer
25
+ # consumption preferences based on the results of its analysis and, for JSON content that
26
+ # is timestamped, can report temporal behavior.
27
+ # * For information about the meaning of the models that the service uses to describe
28
+ # personality characteristics, see [Personality
29
+ # models](https://console.bluemix.net/docs/services/personality-insights/models.html).
30
+ # * For information about the meaning of the consumption preferences, see [Consumption
31
+ # preferences](https://console.bluemix.net/docs/services/personality-insights/preferences.html).
32
+ #
33
+ #
34
+ # **Note:** Request logging is disabled for the Personality Insights service. The service
35
+ # neither logs nor retains data from requests and responses, regardless of whether the
36
+ # `X-Watson-Learning-Opt-Out` request header is set.
37
+
38
+ require "concurrent"
39
+ require "erb"
40
+ require "json"
41
+ require_relative "./detailed_response"
42
+
43
+ require_relative "./watson_service"
44
+
45
+ module IBMWatson
46
+ ##
47
+ # The Personality Insights V3 service.
48
+ class PersonalityInsightsV3
49
+ include Concurrent::Async
50
+ ##
51
+ # @!method initialize(args)
52
+ # Construct a new client for the Personality Insights service.
53
+ #
54
+ # @param args [Hash] The args to initialize with
55
+ # @option args version [String] The API version date to use with the service, in
56
+ # "YYYY-MM-DD" format. Whenever the API is changed in a backwards
57
+ # incompatible way, a new minor version of the API is released.
58
+ # The service uses the API version for the date you specify, or
59
+ # the most recent version before that date. Note that you should
60
+ # not programmatically specify the current date at runtime, in
61
+ # case the API has been updated since your application's release.
62
+ # Instead, specify a version date that is compatible with your
63
+ # application, and don't change it until your application is
64
+ # ready for a later version.
65
+ # @option args url [String] The base url to use when contacting the service (e.g.
66
+ # "https://gateway.watsonplatform.net/personality-insights/api").
67
+ # The base url may differ between Bluemix regions.
68
+ # @option args username [String] The username used to authenticate with the service.
69
+ # Username and password credentials are only required to run your
70
+ # application locally or outside of Bluemix. When running on
71
+ # Bluemix, the credentials will be automatically loaded from the
72
+ # `VCAP_SERVICES` environment variable.
73
+ # @option args password [String] The password used to authenticate with the service.
74
+ # Username and password credentials are only required to run your
75
+ # application locally or outside of Bluemix. When running on
76
+ # Bluemix, the credentials will be automatically loaded from the
77
+ # `VCAP_SERVICES` environment variable.
78
+ # @option args iam_api_key [String] An API key that can be used to request IAM tokens. If
79
+ # this API key is provided, the SDK will manage the token and handle the
80
+ # refreshing.
81
+ # @option args iam_access_token [String] An IAM access token is fully managed by the application.
82
+ # Responsibility falls on the application to refresh the token, either before
83
+ # it expires or reactively upon receiving a 401 from the service as any requests
84
+ # made with an expired token will fail.
85
+ # @option args iam_url [String] An optional URL for the IAM service API. Defaults to
86
+ # 'https://iam.ng.bluemix.net/identity/token'.
87
+ def initialize(args = {})
88
+ @__async_initialized__ = false
89
+ super()
90
+ defaults = {}
91
+ defaults[:version] = nil
92
+ defaults[:url] = "https://gateway.watsonplatform.net/personality-insights/api"
93
+ defaults[:username] = nil
94
+ defaults[:password] = nil
95
+ defaults[:iam_api_key] = nil
96
+ defaults[:iam_access_token] = nil
97
+ defaults[:iam_url] = nil
98
+ args = defaults.merge(args)
99
+ @watson_service = WatsonService.new(
100
+ vcap_services_name: "personality_insights",
101
+ url: args[:url],
102
+ username: args[:username],
103
+ password: args[:password],
104
+ iam_api_key: args[:iam_api_key],
105
+ iam_access_token: args[:iam_access_token],
106
+ iam_url: args[:iam_url],
107
+ use_vcap_services: true
108
+ )
109
+ @version = args[:version]
110
+ end
111
+
112
+ # :nocov:
113
+ def add_default_headers(headers: {})
114
+ @watson_service.add_default_headers(headers: headers)
115
+ end
116
+
117
+ def _iam_access_token(iam_access_token:)
118
+ @watson_service._iam_access_token(iam_access_token: iam_access_token)
119
+ end
120
+
121
+ def _iam_api_key(iam_api_key:)
122
+ @watson_service._iam_api_key(iam_api_key: iam_api_key)
123
+ end
124
+
125
+ # @return [DetailedResponse]
126
+ def request(args)
127
+ @watson_service.request(args)
128
+ end
129
+
130
+ # @note Chainable
131
+ # @param headers [Hash] Custom headers to be sent with the request
132
+ # @return [self]
133
+ def headers(headers)
134
+ @watson_service.headers(headers)
135
+ self
136
+ end
137
+
138
+ def password=(password)
139
+ @watson_service.password = password
140
+ end
141
+
142
+ def password
143
+ @watson_service.password
144
+ end
145
+
146
+ def username=(username)
147
+ @watson_service.username = username
148
+ end
149
+
150
+ def username
151
+ @watson_service.username
152
+ end
153
+
154
+ def url=(url)
155
+ @watson_service.url = url
156
+ end
157
+
158
+ def url
159
+ @watson_service.url
160
+ end
161
+ # :nocov:
162
+ #########################
163
+ # Methods
164
+ #########################
165
+
166
+ ##
167
+ # @!method profile(content:, content_type:, accept: nil, content_language: nil, accept_language: nil, raw_scores: nil, csv_headers: nil, consumption_preferences: nil)
168
+ # Get profile.
169
+ # Generates a personality profile for the author of the input text. The service
170
+ # accepts a maximum of 20 MB of input content, but it requires much less text to
171
+ # produce an accurate profile; for more information, see [Providing sufficient
172
+ # input](https://console.bluemix.net/docs/services/personality-insights/input.html#sufficient).
173
+ # The service analyzes text in Arabic, English, Japanese, Korean, or Spanish and
174
+ # returns its results in a variety of languages. You can provide plain text, HTML,
175
+ # or JSON input by specifying the **Content-Type** parameter; the default is
176
+ # `text/plain`. Request a JSON or comma-separated values (CSV) response by
177
+ # specifying the **Accept** parameter; CSV output includes a fixed number of columns
178
+ # and optional headers.
179
+ #
180
+ # Per the JSON specification, the default character encoding for JSON content is
181
+ # effectively always UTF-8; per the HTTP specification, the default encoding for
182
+ # plain text and HTML is ISO-8859-1 (effectively, the ASCII character set). When
183
+ # specifying a content type of plain text or HTML, include the `charset` parameter
184
+ # to indicate the character encoding of the input text; for example: `Content-Type:
185
+ # text/plain;charset=utf-8`.
186
+ #
187
+ # For detailed information about calling the service and the responses it can
188
+ # generate, see [Requesting a
189
+ # profile](https://console.bluemix.net/docs/services/personality-insights/input.html),
190
+ # [Understanding a JSON
191
+ # profile](https://console.bluemix.net/docs/services/personality-insights/output.html),
192
+ # and [Understanding a CSV
193
+ # profile](https://console.bluemix.net/docs/services/personality-insights/output-csv.html).
194
+ # @param content [Content] A maximum of 20 MB of content to analyze, though the service requires much less
195
+ # text; for more information, see [Providing sufficient
196
+ # input](https://console.bluemix.net/docs/services/personality-insights/input.html#sufficient).
197
+ # For JSON input, provide an object of type `Content`.
198
+ # @param content_type [String] The type of the input. A character encoding can be specified by including a
199
+ # `charset` parameter. For example, 'text/html;charset=utf-8'.
200
+ # @param accept [String] The type of the response: application/json or text/csv. A character encoding can
201
+ # be specified by including a `charset` parameter. For example,
202
+ # 'text/csv;charset=utf-8'.
203
+ # @param content_language [String] The language of the input text for the request: Arabic, English, Japanese, Korean,
204
+ # or Spanish. Regional variants are treated as their parent language; for example,
205
+ # `en-US` is interpreted as `en`.
206
+ #
207
+ # The effect of the **Content-Language** parameter depends on the **Content-Type**
208
+ # parameter. When **Content-Type** is `text/plain` or `text/html`,
209
+ # **Content-Language** is the only way to specify the language. When
210
+ # **Content-Type** is `application/json`, **Content-Language** overrides a language
211
+ # specified with the `language` parameter of a `ContentItem` object, and content
212
+ # items that specify a different language are ignored; omit this parameter to base
213
+ # the language on the specification of the content items. You can specify any
214
+ # combination of languages for **Content-Language** and **Accept-Language**.
215
+ # @param accept_language [String] The desired language of the response. For two-character arguments, regional
216
+ # variants are treated as their parent language; for example, `en-US` is interpreted
217
+ # as `en`. You can specify any combination of languages for the input and response
218
+ # content.
219
+ # @param raw_scores [Boolean] Indicates whether a raw score in addition to a normalized percentile is returned
220
+ # for each characteristic; raw scores are not compared with a sample population. By
221
+ # default, only normalized percentiles are returned.
222
+ # @param csv_headers [Boolean] Indicates whether column labels are returned with a CSV response. By default, no
223
+ # column labels are returned. Applies only when the **Accept** parameter is set to
224
+ # `text/csv`.
225
+ # @param consumption_preferences [Boolean] Indicates whether consumption preferences are returned with the results. By
226
+ # default, no consumption preferences are returned.
227
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
228
+ def profile(content:, content_type:, accept: nil, content_language: nil, accept_language: nil, raw_scores: nil, csv_headers: nil, consumption_preferences: nil)
229
+ raise ArgumentError("content must be provided") if content.nil?
230
+ raise ArgumentError("content_type must be provided") if content_type.nil?
231
+ headers = {
232
+ "Content-Type" => content_type,
233
+ "Accept" => accept,
234
+ "Content-Language" => content_language,
235
+ "Accept-Language" => accept_language
236
+ }
237
+ params = {
238
+ "version" => @version,
239
+ "raw_scores" => raw_scores,
240
+ "csv_headers" => csv_headers,
241
+ "consumption_preferences" => consumption_preferences
242
+ }
243
+ if content_type == "application/json" && content.instance_of?(Hash)
244
+ data = content.to_json
245
+ else
246
+ data = content
247
+ end
248
+ method_url = "/v3/profile"
249
+ response = request(
250
+ method: "POST",
251
+ url: method_url,
252
+ headers: headers,
253
+ params: params,
254
+ data: data,
255
+ accept_json: true
256
+ )
257
+ response
258
+ end
259
+ end
260
+ end
@@ -0,0 +1,2153 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2018 IBM All Rights Reserved.
4
+ #
5
+ # Licensed under the Apache License, Version 2.0 (the "License");
6
+ # you may not use this file except in compliance with the License.
7
+ # You may obtain a copy of the License at
8
+ #
9
+ # http://www.apache.org/licenses/LICENSE-2.0
10
+ #
11
+ # Unless required by applicable law or agreed to in writing, software
12
+ # distributed under the License is distributed on an "AS IS" BASIS,
13
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ # See the License for the specific language governing permissions and
15
+ # limitations under the License.
16
+
17
+ # The IBM® Speech to Text service provides an API that uses IBM's speech-recognition
18
+ # capabilities to produce transcripts of spoken audio. The service can transcribe speech
19
+ # from various languages and audio formats. It addition to basic transcription, the
20
+ # service can produce detailed information about many aspects of the audio. For most
21
+ # languages, the service supports two sampling rates, broadband and narrowband. It returns
22
+ # all JSON response content in the UTF-8 character set. For more information about the
23
+ # service, see the [IBM® Cloud
24
+ # documentation](https://console.bluemix.net/docs/services/speech-to-text/index.html).
25
+ #
26
+ # ### API usage guidelines
27
+ # * **Audio formats:** The service accepts audio in many formats (MIME types). See [Audio
28
+ # formats](https://console.bluemix.net/docs/services/speech-to-text/audio-formats.html).
29
+ # * **HTTP interfaces:** The service provides three HTTP interfaces for speech
30
+ # recognition. The sessionless interface includes a single synchronous method. The
31
+ # session-based interface includes multiple synchronous methods for maintaining a long,
32
+ # multi-turn exchange with the service. And the asynchronous interface provides multiple
33
+ # methods that use registered callbacks and polling for non-blocking recognition. See [The
34
+ # HTTP REST interface](https://console.bluemix.net/docs/services/speech-to-text/http.html)
35
+ # and [The asynchronous HTTP
36
+ # interface](https://console.bluemix.net/docs/services/speech-to-text/async.html).
37
+ # * **WebSocket interface:** The service also offers a WebSocket interface for speech
38
+ # recognition. The WebSocket interface provides a full-duplex, low-latency communication
39
+ # channel. Clients send requests and audio to the service and receive results over a
40
+ # single connection in an asynchronous fashion. See [The WebSocket
41
+ # interface](https://console.bluemix.net/docs/services/speech-to-text/websockets.html).
42
+ # * **Customization:** Use language model customization to expand the vocabulary of a base
43
+ # model with domain-specific terminology. Use acoustic model customization to adapt a base
44
+ # model for the acoustic characteristics of your audio. Language model customization is
45
+ # generally available for production use by most supported languages; acoustic model
46
+ # customization is beta functionality that is available for all supported languages. See
47
+ # [The customization
48
+ # interface](https://console.bluemix.net/docs/services/speech-to-text/custom.html).
49
+ # * **Customization IDs:** Many methods accept a customization ID to identify a custom
50
+ # language or custom acoustic model. Customization IDs are Globally Unique Identifiers
51
+ # (GUIDs). They are hexadecimal strings that have the format
52
+ # `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
53
+ # * **`X-Watson-Learning-Opt-Out`:** By default, all Watson services log requests and
54
+ # their results. Logging is done only to improve the services for future users. The logged
55
+ # data is not shared or made public. To prevent IBM from accessing your data for general
56
+ # service improvements, set the `X-Watson-Learning-Opt-Out` request header to `true` for
57
+ # all requests. You must set the header on each request that you do not want IBM to access
58
+ # for general service improvements.
59
+ #
60
+ # Methods of the customization interface do not log corpora, words, and audio resources
61
+ # that you use to build custom models. Your training data is never used to improve the
62
+ # service's base models. However, the service does log such data when a custom model is
63
+ # used with a recognition request. You must set the `X-Watson-Learning-Opt-Out` request
64
+ # header to `true` to prevent IBM from accessing the data to improve the service.
65
+ # * **`X-Watson-Metadata`**: This header allows you to associate a customer ID with data
66
+ # that is passed with a request. If necessary, you can use the **Delete labeled data**
67
+ # method to delete the data for a customer ID. See [Information
68
+ # security](https://console.bluemix.net/docs/services/speech-to-text/information-security.html).
69
+
70
+ require "concurrent"
71
+ require "erb"
72
+ require "json"
73
+ require_relative "./detailed_response"
74
+
75
+ require_relative "./watson_service"
76
+
77
+ module IBMWatson
78
+ ##
79
+ # The Speech to Text V1 service.
80
+ class SpeechToTextV1
81
+ include Concurrent::Async
82
+ ##
83
+ # @!method initialize(args)
84
+ # Construct a new client for the Speech to Text service.
85
+ #
86
+ # @param args [Hash] The args to initialize with
87
+ # @option args url [String] The base url to use when contacting the service (e.g.
88
+ # "https://stream.watsonplatform.net/speech-to-text/api").
89
+ # The base url may differ between Bluemix regions.
90
+ # @option args username [String] The username used to authenticate with the service.
91
+ # Username and password credentials are only required to run your
92
+ # application locally or outside of Bluemix. When running on
93
+ # Bluemix, the credentials will be automatically loaded from the
94
+ # `VCAP_SERVICES` environment variable.
95
+ # @option args password [String] The password used to authenticate with the service.
96
+ # Username and password credentials are only required to run your
97
+ # application locally or outside of Bluemix. When running on
98
+ # Bluemix, the credentials will be automatically loaded from the
99
+ # `VCAP_SERVICES` environment variable.
100
+ # @option args iam_api_key [String] An API key that can be used to request IAM tokens. If
101
+ # this API key is provided, the SDK will manage the token and handle the
102
+ # refreshing.
103
+ # @option args iam_access_token [String] An IAM access token is fully managed by the application.
104
+ # Responsibility falls on the application to refresh the token, either before
105
+ # it expires or reactively upon receiving a 401 from the service as any requests
106
+ # made with an expired token will fail.
107
+ # @option args iam_url [String] An optional URL for the IAM service API. Defaults to
108
+ # 'https://iam.ng.bluemix.net/identity/token'.
109
+ def initialize(args = {})
110
+ @__async_initialized__ = false
111
+ super()
112
+ defaults = {}
113
+ defaults[:url] = "https://stream.watsonplatform.net/speech-to-text/api"
114
+ defaults[:username] = nil
115
+ defaults[:password] = nil
116
+ defaults[:iam_api_key] = nil
117
+ defaults[:iam_access_token] = nil
118
+ defaults[:iam_url] = nil
119
+ args = defaults.merge(args)
120
+ @watson_service = WatsonService.new(
121
+ vcap_services_name: "speech_to_text",
122
+ url: args[:url],
123
+ username: args[:username],
124
+ password: args[:password],
125
+ iam_api_key: args[:iam_api_key],
126
+ iam_access_token: args[:iam_access_token],
127
+ iam_url: args[:iam_url],
128
+ use_vcap_services: true
129
+ )
130
+ end
131
+
132
+ # :nocov:
133
+ def add_default_headers(headers: {})
134
+ @watson_service.add_default_headers(headers: headers)
135
+ end
136
+
137
+ def _iam_access_token(iam_access_token:)
138
+ @watson_service._iam_access_token(iam_access_token: iam_access_token)
139
+ end
140
+
141
+ def _iam_api_key(iam_api_key:)
142
+ @watson_service._iam_api_key(iam_api_key: iam_api_key)
143
+ end
144
+
145
+ # @return [DetailedResponse]
146
+ def request(args)
147
+ @watson_service.request(args)
148
+ end
149
+
150
+ # @note Chainable
151
+ # @param headers [Hash] Custom headers to be sent with the request
152
+ # @return [self]
153
+ def headers(headers)
154
+ @watson_service.headers(headers)
155
+ self
156
+ end
157
+
158
+ def password=(password)
159
+ @watson_service.password = password
160
+ end
161
+
162
+ def password
163
+ @watson_service.password
164
+ end
165
+
166
+ def username=(username)
167
+ @watson_service.username = username
168
+ end
169
+
170
+ def username
171
+ @watson_service.username
172
+ end
173
+
174
+ def url=(url)
175
+ @watson_service.url = url
176
+ end
177
+
178
+ def url
179
+ @watson_service.url
180
+ end
181
+ # :nocov:
182
+ #########################
183
+ # Models
184
+ #########################
185
+
186
+ ##
187
+ # @!method list_models
188
+ # List models.
189
+ # Lists all language models that are available for use with the service. The
190
+ # information includes the name of the model and its minimum sampling rate in Hertz,
191
+ # among other things.
192
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
193
+ def list_models
194
+ headers = {
195
+ }
196
+ method_url = "/v1/models"
197
+ response = request(
198
+ method: "GET",
199
+ url: method_url,
200
+ headers: headers,
201
+ accept_json: true
202
+ )
203
+ response
204
+ end
205
+
206
+ ##
207
+ # @!method get_model(model_id:)
208
+ # Get a model.
209
+ # Gets information for a single specified language model that is available for use
210
+ # with the service. The information includes the name of the model and its minimum
211
+ # sampling rate in Hertz, among other things.
212
+ # @param model_id [String] The identifier of the model in the form of its name from the output of the **Get
213
+ # models** method.
214
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
215
+ def get_model(model_id:)
216
+ raise ArgumentError("model_id must be provided") if model_id.nil?
217
+ headers = {
218
+ }
219
+ method_url = "/v1/models/%s" % [ERB::Util.url_encode(model_id)]
220
+ response = request(
221
+ method: "GET",
222
+ url: method_url,
223
+ headers: headers,
224
+ accept_json: true
225
+ )
226
+ response
227
+ end
228
+ #########################
229
+ # Sessionless
230
+ #########################
231
+
232
+ ##
233
+ # @!method recognize(audio:, content_type:, model: nil, 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)
234
+ # Recognize audio.
235
+ # Sends audio and returns transcription results for a sessionless recognition
236
+ # request. Returns only the final results; to enable interim results, use
237
+ # session-based requests or the WebSocket API. The service imposes a data size limit
238
+ # of 100 MB. It automatically detects the endianness of the incoming audio and, for
239
+ # audio that includes multiple channels, downmixes the audio to one-channel mono
240
+ # during transcoding. (For the `audio/l16` format, you can specify the endianness.)
241
+ #
242
+ # ### Streaming mode
243
+ #
244
+ # For requests to transcribe live audio as it becomes available, you must set the
245
+ # `Transfer-Encoding` header to `chunked` to use streaming mode. In streaming mode,
246
+ # the server closes the connection (status code 408) if the service receives no data
247
+ # chunk for 30 seconds and the service has no audio to transcribe for 30 seconds.
248
+ # The server also closes the connection (status code 400) if no speech is detected
249
+ # for `inactivity_timeout` seconds of audio (not processing time); use the
250
+ # `inactivity_timeout` parameter to change the default of 30 seconds.
251
+ #
252
+ # ### Audio formats (content types)
253
+ #
254
+ # Use the `Content-Type` header to specify the audio format (MIME type) of the
255
+ # audio. The service accepts the following formats:
256
+ # * `audio/basic` (Use only with narrowband models.)
257
+ # * `audio/flac`
258
+ # * `audio/l16` (Specify the sampling rate (`rate`) and optionally the number of
259
+ # channels (`channels`) and endianness (`endianness`) of the audio.)
260
+ # * `audio/mp3`
261
+ # * `audio/mpeg`
262
+ # * `audio/mulaw` (Specify the sampling rate (`rate`) of the audio.)
263
+ # * `audio/ogg` (The service automatically detects the codec of the input audio.)
264
+ # * `audio/ogg;codecs=opus`
265
+ # * `audio/ogg;codecs=vorbis`
266
+ # * `audio/wav` (Provide audio with a maximum of nine channels.)
267
+ # * `audio/webm` (The service automatically detects the codec of the input audio.)
268
+ # * `audio/webm;codecs=opus`
269
+ # * `audio/webm;codecs=vorbis`
270
+ #
271
+ # For information about the supported audio formats, including specifying the
272
+ # sampling rate, channels, and endianness for the indicated formats, see [Audio
273
+ # formats](https://console.bluemix.net/docs/services/speech-to-text/audio-formats.html).
274
+ #
275
+ #
276
+ # ### Multipart speech recognition
277
+ #
278
+ # The method also supports multipart recognition requests. With multipart requests,
279
+ # you pass all audio data as multipart form data. You specify some parameters as
280
+ # request headers and query parameters, but you pass JSON metadata as form data to
281
+ # control most aspects of the transcription.
282
+ #
283
+ # The multipart approach is intended for use with browsers for which JavaScript is
284
+ # disabled or when the parameters used with the request are greater than the 8 KB
285
+ # limit imposed by most HTTP servers and proxies. You can encounter this limit, for
286
+ # example, if you want to spot a very large number of keywords.
287
+ #
288
+ # For information about submitting a multipart request, see [Submitting multipart
289
+ # requests as form
290
+ # data](https://console.bluemix.net/docs/services/speech-to-text/http.html#HTTP-multi).
291
+ # @param audio [String] The audio to transcribe in the format specified by the `Content-Type` header.
292
+ # @param content_type [String] The type of the input.
293
+ # @param model [String] The identifier of the model that is to be used for the recognition request or, for
294
+ # the **Create a session** method, with the new session.
295
+ # @param customization_id [String] The customization ID (GUID) of a custom language model that is to be used with the
296
+ # recognition request or, for the **Create a session** method, with the new session.
297
+ # The base model of the specified custom language model must match the model
298
+ # specified with the `model` parameter. You must make the request with service
299
+ # credentials created for the instance of the service that owns the custom model. By
300
+ # default, no custom language model is used.
301
+ # @param acoustic_customization_id [String] The customization ID (GUID) of a custom acoustic model that is to be used with the
302
+ # recognition request or, for the **Create a session** method, with the new session.
303
+ # The base model of the specified custom acoustic model must match the model
304
+ # specified with the `model` parameter. You must make the request with service
305
+ # credentials created for the instance of the service that owns the custom model. By
306
+ # default, no custom acoustic model is used.
307
+ # @param base_model_version [String] The version of the specified base model that is to be used with recognition
308
+ # request or, for the **Create a session** method, with the new session. Multiple
309
+ # versions of a base model can exist when a model is updated for internal
310
+ # improvements. The parameter is intended primarily for use with custom models that
311
+ # have been upgraded for a new base model. The default value depends on whether the
312
+ # parameter is used with or without a custom model. For more information, see [Base
313
+ # model
314
+ # version](https://console.bluemix.net/docs/services/speech-to-text/input.html#version).
315
+ # @param customization_weight [Float] If you specify the customization ID (GUID) of a custom language model with the
316
+ # recognition request or, for sessions, with the **Create a session** method, the
317
+ # customization weight tells the service how much weight to give to words from the
318
+ # custom language model compared to those from the base model for the current
319
+ # request.
320
+ #
321
+ # Specify a value between 0.0 and 1.0. Unless a different customization weight was
322
+ # specified for the custom model when it was trained, the default value is 0.3. A
323
+ # customization weight that you specify overrides a weight that was specified when
324
+ # the custom model was trained.
325
+ #
326
+ # The default value yields the best performance in general. Assign a higher value if
327
+ # your audio makes frequent use of OOV words from the custom model. Use caution when
328
+ # setting the weight: a higher value can improve the accuracy of phrases from the
329
+ # custom model's domain, but it can negatively affect performance on non-domain
330
+ # phrases.
331
+ # @param inactivity_timeout [Fixnum] The time in seconds after which, if only silence (no speech) is detected in
332
+ # submitted audio, the connection is closed with a 400 error. The parameter is
333
+ # useful for stopping audio submission from a live microphone when a user simply
334
+ # walks away. Use `-1` for infinity.
335
+ # @param keywords [Array[String]] An array of keyword strings to spot in the audio. Each keyword string can include
336
+ # one or more tokens. Keywords are spotted only in the final results, not in interim
337
+ # hypotheses. If you specify any keywords, you must also specify a keywords
338
+ # threshold. You can spot a maximum of 1000 keywords. Omit the parameter or specify
339
+ # an empty array if you do not need to spot keywords.
340
+ # @param keywords_threshold [Float] A confidence value that is the lower bound for spotting a keyword. A word is
341
+ # considered to match a keyword if its confidence is greater than or equal to the
342
+ # threshold. Specify a probability between 0 and 1 inclusive. No keyword spotting is
343
+ # performed if you omit the parameter. If you specify a threshold, you must also
344
+ # specify one or more keywords.
345
+ # @param max_alternatives [Fixnum] The maximum number of alternative transcripts to be returned. By default, a single
346
+ # transcription is returned.
347
+ # @param word_alternatives_threshold [Float] A confidence value that is the lower bound for identifying a hypothesis as a
348
+ # possible word alternative (also known as \"Confusion Networks\"). An alternative
349
+ # word is considered if its confidence is greater than or equal to the threshold.
350
+ # Specify a probability between 0 and 1 inclusive. No alternative words are computed
351
+ # if you omit the parameter.
352
+ # @param word_confidence [Boolean] If `true`, a confidence measure in the range of 0 to 1 is returned for each word.
353
+ # By default, no word confidence measures are returned.
354
+ # @param timestamps [Boolean] If `true`, time alignment is returned for each word. By default, no timestamps are
355
+ # returned.
356
+ # @param profanity_filter [Boolean] If `true` (the default), filters profanity from all output except for keyword
357
+ # results by replacing inappropriate words with a series of asterisks. Set the
358
+ # parameter to `false` to return results with no censoring. Applies to US English
359
+ # transcription only.
360
+ # @param smart_formatting [Boolean] If `true`, converts dates, times, series of digits and numbers, phone numbers,
361
+ # currency values, and internet addresses into more readable, conventional
362
+ # representations in the final transcript of a recognition request. For US English,
363
+ # also converts certain keyword strings to punctuation symbols. By default, no smart
364
+ # formatting is performed. Applies to US English and Spanish transcription only.
365
+ # @param speaker_labels [Boolean] If `true`, the response includes labels that identify which words were spoken by
366
+ # which participants in a multi-person exchange. By default, no speaker labels are
367
+ # returned. Setting `speaker_labels` to `true` forces the `timestamps` parameter to
368
+ # be `true`, regardless of whether you specify `false` for the parameter.
369
+ #
370
+ # To determine whether a language model supports speaker labels, use the **Get
371
+ # models** method and check that the attribute `speaker_labels` is set to `true`.
372
+ # You can also refer to [Speaker
373
+ # labels](https://console.bluemix.net/docs/services/speech-to-text/output.html#speaker_labels).
374
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
375
+ def recognize(audio:, content_type:, model: nil, 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)
376
+ raise ArgumentError("audio must be provided") if audio.nil?
377
+ raise ArgumentError("content_type must be provided") if content_type.nil?
378
+ headers = {
379
+ "Content-Type" => content_type
380
+ }
381
+ params = {
382
+ "model" => model,
383
+ "customization_id" => customization_id,
384
+ "acoustic_customization_id" => acoustic_customization_id,
385
+ "base_model_version" => base_model_version,
386
+ "customization_weight" => customization_weight,
387
+ "inactivity_timeout" => inactivity_timeout,
388
+ "keywords" => keywords.to_a,
389
+ "keywords_threshold" => keywords_threshold,
390
+ "max_alternatives" => max_alternatives,
391
+ "word_alternatives_threshold" => word_alternatives_threshold,
392
+ "word_confidence" => word_confidence,
393
+ "timestamps" => timestamps,
394
+ "profanity_filter" => profanity_filter,
395
+ "smart_formatting" => smart_formatting,
396
+ "speaker_labels" => speaker_labels
397
+ }
398
+ data = audio
399
+ method_url = "/v1/recognize"
400
+ response = request(
401
+ method: "POST",
402
+ url: method_url,
403
+ headers: headers,
404
+ params: params,
405
+ data: data,
406
+ accept_json: true
407
+ )
408
+ response
409
+ end
410
+
411
+ # @!method recognize_with_websocket(audio: nil,chunk_data: false,content_type: "audio/l16; rate=44100",model: "en-US_BroadbandModel",recognize_callback: nil,customization_id: nil,acoustic_customization_id: nil,customization_weight: nil,version: nil,inactivity_timeout: 30,interim_results: false,keywords: nil,keywords_threshold: nil,max_alternatives: 1,word_alternatives_threshold: nil,word_confidence: false,timestamps: false,profanity_filter: nil,smart_formatting: false,speaker_labels: nil)
412
+ # Sends audio for speech recognition using web sockets.
413
+ # @param audio [IO] Audio to transcribe in the format specified by the `Content-Type` header.
414
+ # @param chunk_data [Boolean] If true, then the WebSocketClient will expect to receive data in chunks rather than as a single audio file
415
+ # @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.
416
+ # @param model [String] The identifier of the model to be used for the recognition request.
417
+ # @param recognize_callback [RecognizeCallback] The instance handling events returned from the service.
418
+ # @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.
419
+ # @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.
420
+ # @param customization_weight [Float] If you specify a `customization_id` with the request, you can use the `customization_weight` parameter to tell the service how much weight to give to words from the custom language model compared to those from the base model for speech recognition. Specify a value between 0.0 and 1.0. Unless a different customization weight was specified for the custom model when it was trained, the default value is 0.3. A customization weight that you specify overrides a weight that was specified when the custom model was trained. The default value yields the best performance in general. Assign a higher value if your audio makes frequent use of OOV words from the custom model. Use caution when setting the weight: a higher value can improve the accuracy of phrases from the custom model's domain, but it can negatively affect performance on non-domain phrases.
421
+ # @param 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).
422
+ # @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.
423
+ # @param interim_results [Boolean] Send back non-final previews of each "sentence" as it is being processed. These results are ignored in text mode.
424
+ # @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.
425
+ # @param keywords_threshold [Float] Confidence value that is the lower bound for spotting a keyword. A word is considered to match a keyword if its confidence is greater than or equal to the threshold. Specify a probability between 0 and 1 inclusive. No keyword spotting is performed if you omit the parameter. If you specify a threshold, you must also specify one or more keywords.
426
+ # @param max_alternatives [Integer] Maximum number of alternative transcripts to be returned. By default, a single transcription is returned.
427
+ # @param word_alternatives_threshold [Float] Confidence value that is the lower bound for identifying a hypothesis as a possible word alternative (also known as \"Confusion Networks\"). An alternative word is considered if its confidence is greater than or equal to the threshold. Specify a probability between 0 and 1 inclusive. No alternative words are computed if you omit the parameter.
428
+ # @param word_confidence [Boolean] If `true`, confidence measure per word is returned.
429
+ # @param timestamps [Boolean] If `true`, time alignment for each word is returned.
430
+ # @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.
431
+ # @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.
432
+ # @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).
433
+ # @return [WebSocketClient] Returns a new WebSocketClient object
434
+ def recognize_with_websocket(
435
+ audio: nil,
436
+ chunk_data: false,
437
+ content_type: "audio/l16; rate=44100",
438
+ model: "en-US_BroadbandModel",
439
+ recognize_callback: nil,
440
+ customization_id: nil,
441
+ acoustic_customization_id: nil,
442
+ customization_weight: nil,
443
+ version: nil,
444
+ inactivity_timeout: 30,
445
+ interim_results: false,
446
+ keywords: nil,
447
+ keywords_threshold: nil,
448
+ max_alternatives: 1,
449
+ word_alternatives_threshold: nil,
450
+ word_confidence: false,
451
+ timestamps: false,
452
+ profanity_filter: nil,
453
+ smart_formatting: false,
454
+ speaker_labels: nil
455
+ )
456
+ raise ArgumentError("Audio must be provided") if audio.nil? && !chunk_data
457
+ raise ArgumentError("Recognize callback must be provided") if recognize_callback.nil?
458
+ raise TypeError("Callback is not a derived class of RecognizeCallback") unless recognize_callback.is_a?(RecognizeCallback)
459
+
460
+ require_relative("./websocket/speech_to_text_websocket_listener.rb")
461
+
462
+ headers = {}
463
+ headers = @watson_service.conn.default_options.headers.to_hash unless @watson_service.conn.default_options.headers.to_hash.empty?
464
+ headers["Authorization"] = "Basic " + Base64.strict_encode64("#{@watson_service.username}:#{@watson_service.password}")
465
+ url = @watson_service.url.gsub("https:", "wss:")
466
+ params = {
467
+ "model" => model,
468
+ "customization_id" => customization_id,
469
+ "acoustic_customization_id" => acoustic_customization_id,
470
+ "customization_weight" => customization_weight,
471
+ "version" => version
472
+ }
473
+ params.delete_if { |_, v| v.nil? }
474
+ url += "/v1/recognize?" + HTTP::URI.form_encode(params)
475
+
476
+ options = {
477
+ "content_type" => content_type,
478
+ "inactivity_timeout" => inactivity_timeout,
479
+ "interim_results" => interim_results,
480
+ "keywords" => keywords,
481
+ "keywords_threshold" => keywords_threshold,
482
+ "max_alternatives" => max_alternatives,
483
+ "word_alternatives_threshold" => word_alternatives_threshold,
484
+ "word_confidence" => word_confidence,
485
+ "timestamps" => timestamps,
486
+ "profanity_filter" => profanity_filter,
487
+ "smart_formatting" => smart_formatting,
488
+ "speaker_labels" => speaker_labels
489
+ }
490
+ options.delete_if { |_, v| v.nil? }
491
+ WebSocketClient.new(audio: audio, chunk_data: chunk_data, options: options, recognize_callback: recognize_callback, url: url, headers: headers)
492
+ end
493
+
494
+ #########################
495
+ # Asynchronous
496
+ #########################
497
+
498
+ ##
499
+ # @!method register_callback(callback_url:, user_secret: nil)
500
+ # Register a callback.
501
+ # Registers a callback URL with the service for use with subsequent asynchronous
502
+ # recognition requests. The service attempts to register, or white-list, the
503
+ # callback URL if it is not already registered by sending a `GET` request to the
504
+ # callback URL. The service passes a random alphanumeric challenge string via the
505
+ # `challenge_string` parameter of the request. The request includes an `Accept`
506
+ # header that specifies `text/plain` as the required response type.
507
+ #
508
+ # To be registered successfully, the callback URL must respond to the `GET` request
509
+ # from the service. The response must send status code 200 and must include the
510
+ # challenge string in its body. Set the `Content-Type` response header to
511
+ # `text/plain`. Upon receiving this response, the service responds to the original
512
+ # registration request with response code 201.
513
+ #
514
+ # The service sends only a single `GET` request to the callback URL. If the service
515
+ # does not receive a reply with a response code of 200 and a body that echoes the
516
+ # challenge string sent by the service within five seconds, it does not white-list
517
+ # the URL; it instead sends status code 400 in response to the **Register a
518
+ # callback** request. If the requested callback URL is already white-listed, the
519
+ # service responds to the initial registration request with response code 200.
520
+ #
521
+ # If you specify a user secret with the request, the service uses it as a key to
522
+ # calculate an HMAC-SHA1 signature of the challenge string in its response to the
523
+ # `POST` request. It sends this signature in the `X-Callback-Signature` header of
524
+ # its `GET` request to the URL during registration. It also uses the secret to
525
+ # calculate a signature over the payload of every callback notification that uses
526
+ # the URL. The signature provides authentication and data integrity for HTTP
527
+ # communications.
528
+ #
529
+ # After you successfully register a callback URL, you can use it with an indefinite
530
+ # number of recognition requests. You can register a maximum of 20 callback URLS in
531
+ # a one-hour span of time. For more information, see [Registering a callback
532
+ # URL](https://console.bluemix.net/docs/services/speech-to-text/async.html#register).
533
+ # @param callback_url [String] An HTTP or HTTPS URL to which callback notifications are to be sent. To be
534
+ # white-listed, the URL must successfully echo the challenge string during URL
535
+ # verification. During verification, the client can also check the signature that
536
+ # the service sends in the `X-Callback-Signature` header to verify the origin of the
537
+ # request.
538
+ # @param user_secret [String] A user-specified string that the service uses to generate the HMAC-SHA1 signature
539
+ # that it sends via the `X-Callback-Signature` header. The service includes the
540
+ # header during URL verification and with every notification sent to the callback
541
+ # URL. It calculates the signature over the payload of the notification. If you omit
542
+ # the parameter, the service does not send the header.
543
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
544
+ def register_callback(callback_url:, user_secret: nil)
545
+ raise ArgumentError("callback_url must be provided") if callback_url.nil?
546
+ headers = {
547
+ }
548
+ params = {
549
+ "callback_url" => callback_url,
550
+ "user_secret" => user_secret
551
+ }
552
+ method_url = "/v1/register_callback"
553
+ response = request(
554
+ method: "POST",
555
+ url: method_url,
556
+ headers: headers,
557
+ params: params,
558
+ accept_json: true
559
+ )
560
+ response
561
+ end
562
+
563
+ ##
564
+ # @!method unregister_callback(callback_url:)
565
+ # Unregister a callback.
566
+ # Unregisters a callback URL that was previously white-listed with a **Register a
567
+ # callback** request for use with the asynchronous interface. Once unregistered, the
568
+ # URL can no longer be used with asynchronous recognition requests.
569
+ # @param callback_url [String] The callback URL that is to be unregistered.
570
+ # @return [nil]
571
+ def unregister_callback(callback_url:)
572
+ raise ArgumentError("callback_url must be provided") if callback_url.nil?
573
+ headers = {
574
+ }
575
+ params = {
576
+ "callback_url" => callback_url
577
+ }
578
+ method_url = "/v1/unregister_callback"
579
+ request(
580
+ method: "POST",
581
+ url: method_url,
582
+ headers: headers,
583
+ params: params,
584
+ accept_json: true
585
+ )
586
+ nil
587
+ end
588
+
589
+ ##
590
+ # @!method create_job(audio:, content_type:, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, 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)
591
+ # Create a job.
592
+ # Creates a job for a new asynchronous recognition request. The job is owned by the
593
+ # user whose service credentials are used to create it. How you learn the status and
594
+ # results of a job depends on the parameters you include with the job creation
595
+ # request:
596
+ # * By callback notification: Include the `callback_url` parameter to specify a URL
597
+ # to which the service is to send callback notifications when the status of the job
598
+ # changes. Optionally, you can also include the `events` and `user_token` parameters
599
+ # to subscribe to specific events and to specify a string that is to be included
600
+ # with each notification for the job.
601
+ # * By polling the service: Omit the `callback_url`, `events`, and `user_token`
602
+ # parameters. You must then use the **Check jobs** or **Check a job** methods to
603
+ # check the status of the job, using the latter to retrieve the results when the job
604
+ # is complete.
605
+ #
606
+ # The two approaches are not mutually exclusive. You can poll the service for job
607
+ # status or obtain results from the service manually even if you include a callback
608
+ # URL. In both cases, you can include the `results_ttl` parameter to specify how
609
+ # long the results are to remain available after the job is complete. For detailed
610
+ # usage information about the two approaches, including callback notifications, see
611
+ # [Creating a
612
+ # job](https://console.bluemix.net/docs/services/speech-to-text/async.html#create).
613
+ # Using the HTTPS **Check a job** method to retrieve results is more secure than
614
+ # receiving them via callback notification over HTTP because it provides
615
+ # confidentiality in addition to authentication and data integrity.
616
+ #
617
+ # The method supports the same basic parameters as other HTTP and WebSocket
618
+ # recognition requests. It also supports the following parameters specific to the
619
+ # asynchronous interface:
620
+ # * `callback_url`
621
+ # * `events`
622
+ # * `user_token`
623
+ # * `results_ttl`
624
+ #
625
+ # The service imposes a data size limit of 100 MB. It automatically detects the
626
+ # endianness of the incoming audio and, for audio that includes multiple channels,
627
+ # downmixes the audio to one-channel mono during transcoding. (For the `audio/l16`
628
+ # format, you can specify the endianness.)
629
+ #
630
+ # ### Audio formats (content types)
631
+ #
632
+ # Use the `Content-Type` parameter to specify the audio format (MIME type) of the
633
+ # audio:
634
+ # * `audio/basic` (Use only with narrowband models.)
635
+ # * `audio/flac`
636
+ # * `audio/l16` (Specify the sampling rate (`rate`) and optionally the number of
637
+ # channels (`channels`) and endianness (`endianness`) of the audio.)
638
+ # * `audio/mp3`
639
+ # * `audio/mpeg`
640
+ # * `audio/mulaw` (Specify the sampling rate (`rate`) of the audio.)
641
+ # * `audio/ogg` (The service automatically detects the codec of the input audio.)
642
+ # * `audio/ogg;codecs=opus`
643
+ # * `audio/ogg;codecs=vorbis`
644
+ # * `audio/wav` (Provide audio with a maximum of nine channels.)
645
+ # * `audio/webm` (The service automatically detects the codec of the input audio.)
646
+ # * `audio/webm;codecs=opus`
647
+ # * `audio/webm;codecs=vorbis`
648
+ #
649
+ # For information about the supported audio formats, including specifying the
650
+ # sampling rate, channels, and endianness for the indicated formats, see [Audio
651
+ # formats](https://console.bluemix.net/docs/services/speech-to-text/audio-formats.html).
652
+ # @param audio [String] The audio to transcribe in the format specified by the `Content-Type` header.
653
+ # @param content_type [String] The type of the input.
654
+ # @param model [String] The identifier of the model that is to be used for the recognition request or, for
655
+ # the **Create a session** method, with the new session.
656
+ # @param callback_url [String] A URL to which callback notifications are to be sent. The URL must already be
657
+ # successfully white-listed by using the **Register a callback** method. You can
658
+ # include the same callback URL with any number of job creation requests. Omit the
659
+ # parameter to poll the service for job completion and results.
660
+ #
661
+ # Use the `user_token` parameter to specify a unique user-specified string with each
662
+ # job to differentiate the callback notifications for the jobs.
663
+ # @param events [String] If the job includes a callback URL, a comma-separated list of notification events
664
+ # to which to subscribe. Valid events are
665
+ # * `recognitions.started` generates a callback notification when the service begins
666
+ # to process the job.
667
+ # * `recognitions.completed` generates a callback notification when the job is
668
+ # complete. You must use the **Check a job** method to retrieve the results before
669
+ # they time out or are deleted.
670
+ # * `recognitions.completed_with_results` generates a callback notification when the
671
+ # job is complete. The notification includes the results of the request.
672
+ # * `recognitions.failed` generates a callback notification if the service
673
+ # experiences an error while processing the job.
674
+ #
675
+ # Omit the parameter to subscribe to the default events: `recognitions.started`,
676
+ # `recognitions.completed`, and `recognitions.failed`. The `recognitions.completed`
677
+ # and `recognitions.completed_with_results` events are incompatible; you can specify
678
+ # only of the two events. If the job does not include a callback URL, omit the
679
+ # parameter.
680
+ # @param user_token [String] If the job includes a callback URL, a user-specified string that the service is to
681
+ # include with each callback notification for the job; the token allows the user to
682
+ # maintain an internal mapping between jobs and notification events. If the job does
683
+ # not include a callback URL, omit the parameter.
684
+ # @param results_ttl [Fixnum] The number of minutes for which the results are to be available after the job has
685
+ # finished. If not delivered via a callback, the results must be retrieved within
686
+ # this time. Omit the parameter to use a time to live of one week. The parameter is
687
+ # valid with or without a callback URL.
688
+ # @param customization_id [String] The customization ID (GUID) of a custom language model that is to be used with the
689
+ # recognition request or, for the **Create a session** method, with the new session.
690
+ # The base model of the specified custom language model must match the model
691
+ # specified with the `model` parameter. You must make the request with service
692
+ # credentials created for the instance of the service that owns the custom model. By
693
+ # default, no custom language model is used.
694
+ # @param acoustic_customization_id [String] The customization ID (GUID) of a custom acoustic model that is to be used with the
695
+ # recognition request or, for the **Create a session** method, with the new session.
696
+ # The base model of the specified custom acoustic model must match the model
697
+ # specified with the `model` parameter. You must make the request with service
698
+ # credentials created for the instance of the service that owns the custom model. By
699
+ # default, no custom acoustic model is used.
700
+ # @param base_model_version [String] The version of the specified base model that is to be used with recognition
701
+ # request or, for the **Create a session** method, with the new session. Multiple
702
+ # versions of a base model can exist when a model is updated for internal
703
+ # improvements. The parameter is intended primarily for use with custom models that
704
+ # have been upgraded for a new base model. The default value depends on whether the
705
+ # parameter is used with or without a custom model. For more information, see [Base
706
+ # model
707
+ # version](https://console.bluemix.net/docs/services/speech-to-text/input.html#version).
708
+ # @param customization_weight [Float] If you specify the customization ID (GUID) of a custom language model with the
709
+ # recognition request or, for sessions, with the **Create a session** method, the
710
+ # customization weight tells the service how much weight to give to words from the
711
+ # custom language model compared to those from the base model for the current
712
+ # request.
713
+ #
714
+ # Specify a value between 0.0 and 1.0. Unless a different customization weight was
715
+ # specified for the custom model when it was trained, the default value is 0.3. A
716
+ # customization weight that you specify overrides a weight that was specified when
717
+ # the custom model was trained.
718
+ #
719
+ # The default value yields the best performance in general. Assign a higher value if
720
+ # your audio makes frequent use of OOV words from the custom model. Use caution when
721
+ # setting the weight: a higher value can improve the accuracy of phrases from the
722
+ # custom model's domain, but it can negatively affect performance on non-domain
723
+ # phrases.
724
+ # @param inactivity_timeout [Fixnum] The time in seconds after which, if only silence (no speech) is detected in
725
+ # submitted audio, the connection is closed with a 400 error. The parameter is
726
+ # useful for stopping audio submission from a live microphone when a user simply
727
+ # walks away. Use `-1` for infinity.
728
+ # @param keywords [Array[String]] An array of keyword strings to spot in the audio. Each keyword string can include
729
+ # one or more tokens. Keywords are spotted only in the final results, not in interim
730
+ # hypotheses. If you specify any keywords, you must also specify a keywords
731
+ # threshold. You can spot a maximum of 1000 keywords. Omit the parameter or specify
732
+ # an empty array if you do not need to spot keywords.
733
+ # @param keywords_threshold [Float] A confidence value that is the lower bound for spotting a keyword. A word is
734
+ # considered to match a keyword if its confidence is greater than or equal to the
735
+ # threshold. Specify a probability between 0 and 1 inclusive. No keyword spotting is
736
+ # performed if you omit the parameter. If you specify a threshold, you must also
737
+ # specify one or more keywords.
738
+ # @param max_alternatives [Fixnum] The maximum number of alternative transcripts to be returned. By default, a single
739
+ # transcription is returned.
740
+ # @param word_alternatives_threshold [Float] A confidence value that is the lower bound for identifying a hypothesis as a
741
+ # possible word alternative (also known as \"Confusion Networks\"). An alternative
742
+ # word is considered if its confidence is greater than or equal to the threshold.
743
+ # Specify a probability between 0 and 1 inclusive. No alternative words are computed
744
+ # if you omit the parameter.
745
+ # @param word_confidence [Boolean] If `true`, a confidence measure in the range of 0 to 1 is returned for each word.
746
+ # By default, no word confidence measures are returned.
747
+ # @param timestamps [Boolean] If `true`, time alignment is returned for each word. By default, no timestamps are
748
+ # returned.
749
+ # @param profanity_filter [Boolean] If `true` (the default), filters profanity from all output except for keyword
750
+ # results by replacing inappropriate words with a series of asterisks. Set the
751
+ # parameter to `false` to return results with no censoring. Applies to US English
752
+ # transcription only.
753
+ # @param smart_formatting [Boolean] If `true`, converts dates, times, series of digits and numbers, phone numbers,
754
+ # currency values, and internet addresses into more readable, conventional
755
+ # representations in the final transcript of a recognition request. For US English,
756
+ # also converts certain keyword strings to punctuation symbols. By default, no smart
757
+ # formatting is performed. Applies to US English and Spanish transcription only.
758
+ # @param speaker_labels [Boolean] If `true`, the response includes labels that identify which words were spoken by
759
+ # which participants in a multi-person exchange. By default, no speaker labels are
760
+ # returned. Setting `speaker_labels` to `true` forces the `timestamps` parameter to
761
+ # be `true`, regardless of whether you specify `false` for the parameter.
762
+ #
763
+ # To determine whether a language model supports speaker labels, use the **Get
764
+ # models** method and check that the attribute `speaker_labels` is set to `true`.
765
+ # You can also refer to [Speaker
766
+ # labels](https://console.bluemix.net/docs/services/speech-to-text/output.html#speaker_labels).
767
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
768
+ def create_job(audio:, content_type:, model: nil, callback_url: nil, events: nil, user_token: nil, results_ttl: nil, 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)
769
+ raise ArgumentError("audio must be provided") if audio.nil?
770
+ raise ArgumentError("content_type must be provided") if content_type.nil?
771
+ headers = {
772
+ "Content-Type" => content_type
773
+ }
774
+ params = {
775
+ "model" => model,
776
+ "callback_url" => callback_url,
777
+ "events" => events,
778
+ "user_token" => user_token,
779
+ "results_ttl" => results_ttl,
780
+ "customization_id" => customization_id,
781
+ "acoustic_customization_id" => acoustic_customization_id,
782
+ "base_model_version" => base_model_version,
783
+ "customization_weight" => customization_weight,
784
+ "inactivity_timeout" => inactivity_timeout,
785
+ "keywords" => keywords.to_a,
786
+ "keywords_threshold" => keywords_threshold,
787
+ "max_alternatives" => max_alternatives,
788
+ "word_alternatives_threshold" => word_alternatives_threshold,
789
+ "word_confidence" => word_confidence,
790
+ "timestamps" => timestamps,
791
+ "profanity_filter" => profanity_filter,
792
+ "smart_formatting" => smart_formatting,
793
+ "speaker_labels" => speaker_labels
794
+ }
795
+ data = audio
796
+ method_url = "/v1/recognitions"
797
+ response = request(
798
+ method: "POST",
799
+ url: method_url,
800
+ headers: headers,
801
+ params: params,
802
+ data: data,
803
+ accept_json: true
804
+ )
805
+ response
806
+ end
807
+
808
+ ##
809
+ # @!method check_jobs
810
+ # Check jobs.
811
+ # Returns the ID and status of the latest 100 outstanding jobs associated with the
812
+ # service credentials with which it is called. The method also returns the creation
813
+ # and update times of each job, and, if a job was created with a callback URL and a
814
+ # user token, the user token for the job. To obtain the results for a job whose
815
+ # status is `completed` or not one of the latest 100 outstanding jobs, use the
816
+ # **Check a job** method. A job and its results remain available until you delete
817
+ # them with the **Delete a job** method or until the job's time to live expires,
818
+ # whichever comes first.
819
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
820
+ def check_jobs
821
+ headers = {
822
+ }
823
+ method_url = "/v1/recognitions"
824
+ response = request(
825
+ method: "GET",
826
+ url: method_url,
827
+ headers: headers,
828
+ accept_json: true
829
+ )
830
+ response
831
+ end
832
+
833
+ ##
834
+ # @!method check_job(id:)
835
+ # Check a job.
836
+ # Returns information about the specified job. The response always includes the
837
+ # status of the job and its creation and update times. If the status is `completed`,
838
+ # the response includes the results of the recognition request. You must submit the
839
+ # request with the service credentials of the user who created the job.
840
+ #
841
+ # You can use the method to retrieve the results of any job, regardless of whether
842
+ # it was submitted with a callback URL and the `recognitions.completed_with_results`
843
+ # event, and you can retrieve the results multiple times for as long as they remain
844
+ # available. Use the **Check jobs** method to request information about the most
845
+ # recent jobs associated with the calling user.
846
+ # @param id [String] The ID of the asynchronous job.
847
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
848
+ def check_job(id:)
849
+ raise ArgumentError("id must be provided") if id.nil?
850
+ headers = {
851
+ }
852
+ method_url = "/v1/recognitions/%s" % [ERB::Util.url_encode(id)]
853
+ response = request(
854
+ method: "GET",
855
+ url: method_url,
856
+ headers: headers,
857
+ accept_json: true
858
+ )
859
+ response
860
+ end
861
+
862
+ ##
863
+ # @!method delete_job(id:)
864
+ # Delete a job.
865
+ # Deletes the specified job. You cannot delete a job that the service is actively
866
+ # processing. Once you delete a job, its results are no longer available. The
867
+ # service automatically deletes a job and its results when the time to live for the
868
+ # results expires. You must submit the request with the service credentials of the
869
+ # user who created the job.
870
+ # @param id [String] The ID of the asynchronous job.
871
+ # @return [nil]
872
+ def delete_job(id:)
873
+ raise ArgumentError("id must be provided") if id.nil?
874
+ headers = {
875
+ }
876
+ method_url = "/v1/recognitions/%s" % [ERB::Util.url_encode(id)]
877
+ request(
878
+ method: "DELETE",
879
+ url: method_url,
880
+ headers: headers,
881
+ accept_json: true
882
+ )
883
+ nil
884
+ end
885
+ #########################
886
+ # Custom language models
887
+ #########################
888
+
889
+ ##
890
+ # @!method create_language_model(name:, base_model_name:, dialect: nil, description: nil)
891
+ # Create a custom language model.
892
+ # Creates a new custom language model for a specified base model. The custom
893
+ # language model can be used only with the base model for which it is created. The
894
+ # model is owned by the instance of the service whose credentials are used to create
895
+ # it.
896
+ # @param name [String] A user-defined name for the new custom language model. Use a name that is unique
897
+ # among all custom language models that you own. Use a localized name that matches
898
+ # the language of the custom model. Use a name that describes the domain of the
899
+ # custom model, such as `Medical custom model` or `Legal custom model`.
900
+ # @param base_model_name [String] The name of the base language model that is to be customized by the new custom
901
+ # language model. The new custom model can be used only with the base model that it
902
+ # customizes. To determine whether a base model supports language model
903
+ # customization, request information about the base model and check that the
904
+ # attribute `custom_language_model` is set to `true`, or refer to [Language support
905
+ # for
906
+ # customization](https://console.bluemix.net/docs/services/speech-to-text/custom.html#languageSupport).
907
+ # @param dialect [String] The dialect of the specified language that is to be used with the custom language
908
+ # model. The parameter is meaningful only for Spanish models, for which the service
909
+ # creates a custom language model that is suited for speech in one of the following
910
+ # dialects:
911
+ # * `es-ES` for Castilian Spanish (the default)
912
+ # * `es-LA` for Latin American Spanish
913
+ # * `es-US` for North American (Mexican) Spanish
914
+ #
915
+ # A specified dialect must be valid for the base model. By default, the dialect
916
+ # matches the language of the base model; for example, `en-US` for either of the US
917
+ # English language models.
918
+ # @param description [String] A description of the new custom language model. Use a localized description that
919
+ # matches the language of the custom model.
920
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
921
+ def create_language_model(name:, base_model_name:, dialect: nil, description: nil)
922
+ raise ArgumentError("name must be provided") if name.nil?
923
+ raise ArgumentError("base_model_name must be provided") if base_model_name.nil?
924
+ headers = {
925
+ }
926
+ data = {
927
+ "name" => name,
928
+ "base_model_name" => base_model_name,
929
+ "dialect" => dialect,
930
+ "description" => description
931
+ }
932
+ method_url = "/v1/customizations"
933
+ response = request(
934
+ method: "POST",
935
+ url: method_url,
936
+ headers: headers,
937
+ json: data,
938
+ accept_json: true
939
+ )
940
+ response
941
+ end
942
+
943
+ ##
944
+ # @!method list_language_models(language: nil)
945
+ # List custom language models.
946
+ # Lists information about all custom language models that are owned by an instance
947
+ # of the service. Use the `language` parameter to see all custom language models for
948
+ # the specified language. Omit the parameter to see all custom language models for
949
+ # all languages. You must use credentials for the instance of the service that owns
950
+ # a model to list information about it.
951
+ # @param language [String] The identifier of the language for which custom language or custom acoustic models
952
+ # are to be returned (for example, `en-US`). Omit the parameter to see all custom
953
+ # language or custom acoustic models owned by the requesting service credentials.
954
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
955
+ def list_language_models(language: nil)
956
+ headers = {
957
+ }
958
+ params = {
959
+ "language" => language
960
+ }
961
+ method_url = "/v1/customizations"
962
+ response = request(
963
+ method: "GET",
964
+ url: method_url,
965
+ headers: headers,
966
+ params: params,
967
+ accept_json: true
968
+ )
969
+ response
970
+ end
971
+
972
+ ##
973
+ # @!method get_language_model(customization_id:)
974
+ # Get a custom language model.
975
+ # Gets information about a specified custom language model. You must use credentials
976
+ # for the instance of the service that owns a model to list information about it.
977
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
978
+ # request with service credentials created for the instance of the service that owns
979
+ # the custom model.
980
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
981
+ def get_language_model(customization_id:)
982
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
983
+ headers = {
984
+ }
985
+ method_url = "/v1/customizations/%s" % [ERB::Util.url_encode(customization_id)]
986
+ response = request(
987
+ method: "GET",
988
+ url: method_url,
989
+ headers: headers,
990
+ accept_json: true
991
+ )
992
+ response
993
+ end
994
+
995
+ ##
996
+ # @!method delete_language_model(customization_id:)
997
+ # Delete a custom language model.
998
+ # Deletes an existing custom language model. The custom model cannot be deleted if
999
+ # another request, such as adding a corpus to the model, is currently being
1000
+ # processed. You must use credentials for the instance of the service that owns a
1001
+ # model to delete it.
1002
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1003
+ # request with service credentials created for the instance of the service that owns
1004
+ # the custom model.
1005
+ # @return [nil]
1006
+ def delete_language_model(customization_id:)
1007
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1008
+ headers = {
1009
+ }
1010
+ method_url = "/v1/customizations/%s" % [ERB::Util.url_encode(customization_id)]
1011
+ request(
1012
+ method: "DELETE",
1013
+ url: method_url,
1014
+ headers: headers,
1015
+ accept_json: true
1016
+ )
1017
+ nil
1018
+ end
1019
+
1020
+ ##
1021
+ # @!method train_language_model(customization_id:, word_type_to_add: nil, customization_weight: nil)
1022
+ # Train a custom language model.
1023
+ # Initiates the training of a custom language model with new corpora, custom words,
1024
+ # or both. After adding, modifying, or deleting corpora or words for a custom
1025
+ # language model, use this method to begin the actual training of the model on the
1026
+ # latest data. You can specify whether the custom language model is to be trained
1027
+ # with all words from its words resource or only with words that were added or
1028
+ # modified by the user. You must use credentials for the instance of the service
1029
+ # that owns a model to train it.
1030
+ #
1031
+ # The training method is asynchronous. It can take on the order of minutes to
1032
+ # complete depending on the amount of data on which the service is being trained and
1033
+ # the current load on the service. The method returns an HTTP 200 response code to
1034
+ # indicate that the training process has begun.
1035
+ #
1036
+ # You can monitor the status of the training by using the **Get a custom language
1037
+ # model** method to poll the model's status. Use a loop to check the status every 10
1038
+ # seconds. The method returns a `LanguageModel` object that includes `status` and
1039
+ # `progress` fields. A status of `available` means that the custom model is trained
1040
+ # and ready to use. The service cannot accept subsequent training requests, or
1041
+ # requests to add new corpora or words, until the existing request completes.
1042
+ #
1043
+ # Training can fail to start for the following reasons:
1044
+ # * The service is currently handling another request for the custom model, such as
1045
+ # another training request or a request to add a corpus or words to the model.
1046
+ # * No training data (corpora or words) have been added to the custom model.
1047
+ # * One or more words that were added to the custom model have invalid sounds-like
1048
+ # pronunciations that you must fix.
1049
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1050
+ # request with service credentials created for the instance of the service that owns
1051
+ # the custom model.
1052
+ # @param word_type_to_add [String] The type of words from the custom language model's words resource on which to
1053
+ # train the model:
1054
+ # * `all` (the default) trains the model on all new words, regardless of whether
1055
+ # they were extracted from corpora or were added or modified by the user.
1056
+ # * `user` trains the model only on new words that were added or modified by the
1057
+ # user; the model is not trained on new words extracted from corpora.
1058
+ # @param customization_weight [Float] Specifies a customization weight for the custom language model. The customization
1059
+ # weight tells the service how much weight to give to words from the custom language
1060
+ # model compared to those from the base model for speech recognition. Specify a
1061
+ # value between 0.0 and 1.0; the default is 0.3.
1062
+ #
1063
+ # The default value yields the best performance in general. Assign a higher value if
1064
+ # your audio makes frequent use of OOV words from the custom model. Use caution when
1065
+ # setting the weight: a higher value can improve the accuracy of phrases from the
1066
+ # custom model's domain, but it can negatively affect performance on non-domain
1067
+ # phrases.
1068
+ #
1069
+ # The value that you assign is used for all recognition requests that use the model.
1070
+ # You can override it for any recognition request by specifying a customization
1071
+ # weight for that request.
1072
+ # @return [nil]
1073
+ def train_language_model(customization_id:, word_type_to_add: nil, customization_weight: nil)
1074
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1075
+ headers = {
1076
+ }
1077
+ params = {
1078
+ "word_type_to_add" => word_type_to_add,
1079
+ "customization_weight" => customization_weight
1080
+ }
1081
+ method_url = "/v1/customizations/%s/train" % [ERB::Util.url_encode(customization_id)]
1082
+ request(
1083
+ method: "POST",
1084
+ url: method_url,
1085
+ headers: headers,
1086
+ params: params,
1087
+ accept_json: true
1088
+ )
1089
+ nil
1090
+ end
1091
+
1092
+ ##
1093
+ # @!method reset_language_model(customization_id:)
1094
+ # Reset a custom language model.
1095
+ # Resets a custom language model by removing all corpora and words from the model.
1096
+ # Resetting a custom language model initializes the model to its state when it was
1097
+ # first created. Metadata such as the name and language of the model are preserved,
1098
+ # but the model's words resource is removed and must be re-created. You must use
1099
+ # credentials for the instance of the service that owns a model to reset it.
1100
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1101
+ # request with service credentials created for the instance of the service that owns
1102
+ # the custom model.
1103
+ # @return [nil]
1104
+ def reset_language_model(customization_id:)
1105
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1106
+ headers = {
1107
+ }
1108
+ method_url = "/v1/customizations/%s/reset" % [ERB::Util.url_encode(customization_id)]
1109
+ request(
1110
+ method: "POST",
1111
+ url: method_url,
1112
+ headers: headers,
1113
+ accept_json: true
1114
+ )
1115
+ nil
1116
+ end
1117
+
1118
+ ##
1119
+ # @!method upgrade_language_model(customization_id:)
1120
+ # Upgrade a custom language model.
1121
+ # Initiates the upgrade of a custom language model to the latest version of its base
1122
+ # language model. The upgrade method is asynchronous. It can take on the order of
1123
+ # minutes to complete depending on the amount of data in the custom model and the
1124
+ # current load on the service. A custom model must be in the `ready` or `available`
1125
+ # state to be upgraded. You must use credentials for the instance of the service
1126
+ # that owns a model to upgrade it.
1127
+ #
1128
+ # The method returns an HTTP 200 response code to indicate that the upgrade process
1129
+ # has begun successfully. You can monitor the status of the upgrade by using the
1130
+ # **Get a custom language model** method to poll the model's status. The method
1131
+ # returns a `LanguageModel` object that includes `status` and `progress` fields. Use
1132
+ # a loop to check the status every 10 seconds. While it is being upgraded, the
1133
+ # custom model has the status `upgrading`. When the upgrade is complete, the model
1134
+ # resumes the status that it had prior to upgrade. The service cannot accept
1135
+ # subsequent requests for the model until the upgrade completes.
1136
+ #
1137
+ # For more information, see [Upgrading custom
1138
+ # models](https://console.bluemix.net/docs/services/speech-to-text/custom-upgrade.html).
1139
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1140
+ # request with service credentials created for the instance of the service that owns
1141
+ # the custom model.
1142
+ # @return [nil]
1143
+ def upgrade_language_model(customization_id:)
1144
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1145
+ headers = {
1146
+ }
1147
+ method_url = "/v1/customizations/%s/upgrade_model" % [ERB::Util.url_encode(customization_id)]
1148
+ request(
1149
+ method: "POST",
1150
+ url: method_url,
1151
+ headers: headers,
1152
+ accept_json: true
1153
+ )
1154
+ nil
1155
+ end
1156
+ #########################
1157
+ # Custom corpora
1158
+ #########################
1159
+
1160
+ ##
1161
+ # @!method list_corpora(customization_id:)
1162
+ # List corpora.
1163
+ # Lists information about all corpora from a custom language model. The information
1164
+ # includes the total number of words and out-of-vocabulary (OOV) words, name, and
1165
+ # status of each corpus. You must use credentials for the instance of the service
1166
+ # that owns a model to list its corpora.
1167
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1168
+ # request with service credentials created for the instance of the service that owns
1169
+ # the custom model.
1170
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1171
+ def list_corpora(customization_id:)
1172
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1173
+ headers = {
1174
+ }
1175
+ method_url = "/v1/customizations/%s/corpora" % [ERB::Util.url_encode(customization_id)]
1176
+ response = request(
1177
+ method: "GET",
1178
+ url: method_url,
1179
+ headers: headers,
1180
+ accept_json: true
1181
+ )
1182
+ response
1183
+ end
1184
+
1185
+ ##
1186
+ # @!method add_corpus(customization_id:, corpus_name:, corpus_file:, allow_overwrite: nil, corpus_filename: nil)
1187
+ # Add a corpus.
1188
+ # Adds a single corpus text file of new training data to a custom language model.
1189
+ # Use multiple requests to submit multiple corpus text files. You must use
1190
+ # credentials for the instance of the service that owns a model to add a corpus to
1191
+ # it. Adding a corpus does not affect the custom language model until you train the
1192
+ # model for the new data by using the **Train a custom language model** method.
1193
+ #
1194
+ # Submit a plain text file that contains sample sentences from the domain of
1195
+ # interest to enable the service to extract words in context. The more sentences you
1196
+ # add that represent the context in which speakers use words from the domain, the
1197
+ # better the service's recognition accuracy. For guidelines about adding a corpus
1198
+ # text file and for information about how the service parses a corpus file, see
1199
+ # [Preparing a corpus text
1200
+ # file](https://console.bluemix.net/docs/services/speech-to-text/language-resource.html#prepareCorpus).
1201
+ #
1202
+ #
1203
+ # The call returns an HTTP 201 response code if the corpus is valid. The service
1204
+ # then asynchronously processes the contents of the corpus and automatically
1205
+ # extracts new words that it finds. This can take on the order of a minute or two to
1206
+ # complete depending on the total number of words and the number of new words in the
1207
+ # corpus, as well as the current load on the service. You cannot submit requests to
1208
+ # add additional corpora or words to the custom model, or to train the model, until
1209
+ # the service's analysis of the corpus for the current request completes. Use the
1210
+ # **List a corpus** method to check the status of the analysis.
1211
+ #
1212
+ # The service auto-populates the model's words resource with any word that is not
1213
+ # found in its base vocabulary; these are referred to as out-of-vocabulary (OOV)
1214
+ # words. You can use the **List custom words** method to examine the words resource,
1215
+ # using other words method to eliminate typos and modify how words are pronounced as
1216
+ # needed.
1217
+ #
1218
+ # To add a corpus file that has the same name as an existing corpus, set the
1219
+ # `allow_overwrite` parameter to `true`; otherwise, the request fails. Overwriting
1220
+ # an existing corpus causes the service to process the corpus text file and extract
1221
+ # OOV words anew. Before doing so, it removes any OOV words associated with the
1222
+ # existing corpus from the model's words resource unless they were also added by
1223
+ # another corpus or they have been modified in some way with the **Add custom
1224
+ # words** or **Add a custom word** method.
1225
+ #
1226
+ # The service limits the overall amount of data that you can add to a custom model
1227
+ # to a maximum of 10 million total words from all corpora combined. Also, you can
1228
+ # add no more than 30 thousand custom (OOV) words to a model; this includes words
1229
+ # that the service extracts from corpora and words that you add directly.
1230
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1231
+ # request with service credentials created for the instance of the service that owns
1232
+ # the custom model.
1233
+ # @param corpus_name [String] The name of the corpus for the custom language model. When adding a corpus, do not
1234
+ # include spaces in the name; use a localized name that matches the language of the
1235
+ # custom model; and do not use the name `user`, which is reserved by the service to
1236
+ # denote custom words added or modified by the user.
1237
+ # @param corpus_file [File] A plain text file that contains the training data for the corpus. Encode the file
1238
+ # in UTF-8 if it contains non-ASCII characters; the service assumes UTF-8 encoding
1239
+ # if it encounters non-ASCII characters. With cURL, use the `--data-binary` option
1240
+ # to upload the file for the request.
1241
+ # @param allow_overwrite [Boolean] If `true`, the specified corpus or audio resource overwrites an existing corpus or
1242
+ # audio resource with the same name. If `false` (the default), the request fails if
1243
+ # a corpus or audio resource with the same name already exists. The parameter has no
1244
+ # effect if a corpus or audio resource with the same name does not already exist.
1245
+ # @param corpus_filename [String] The filename for corpus_file.
1246
+ # @return [nil]
1247
+ def add_corpus(customization_id:, corpus_name:, corpus_file:, allow_overwrite: nil, corpus_filename: nil)
1248
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1249
+ raise ArgumentError("corpus_name must be provided") if corpus_name.nil?
1250
+ raise ArgumentError("corpus_file must be provided") if corpus_file.nil?
1251
+ headers = {
1252
+ }
1253
+ params = {
1254
+ "allow_overwrite" => allow_overwrite
1255
+ }
1256
+ mime_type = "text/plain"
1257
+ unless corpus_file.instance_of?(StringIO) || corpus_file.instance_of?(File)
1258
+ corpus_file = corpus_file.respond_to?(:to_json) ? StringIO.new(corpus_file.to_json) : StringIO.new(corpus_file)
1259
+ end
1260
+ if corpus_filename
1261
+ corpus_file = corpus_file.instance_of?(StringIO) ? HTTP::FormData::File.new(corpus_file, content_type: mime_type, filename: corpus_filename) : HTTP::FormData::File.new(corpus_file.path, content_type: mime_type, filename: corpus_filename)
1262
+ else
1263
+ corpus_file = corpus_file.instance_of?(StringIO) ? HTTP::FormData::File.new(corpus_file, content_type: mime_type) : HTTP::FormData::File.new(corpus_file.path, content_type: mime_type)
1264
+ end
1265
+ method_url = "/v1/customizations/%s/corpora/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(corpus_name)]
1266
+ request(
1267
+ method: "POST",
1268
+ url: method_url,
1269
+ headers: headers,
1270
+ params: params,
1271
+ form: {
1272
+ corpus_file: corpus_file
1273
+ },
1274
+ accept_json: true
1275
+ )
1276
+ nil
1277
+ end
1278
+
1279
+ ##
1280
+ # @!method get_corpus(customization_id:, corpus_name:)
1281
+ # Get a corpus.
1282
+ # Gets information about a corpus from a custom language model. The information
1283
+ # includes the total number of words and out-of-vocabulary (OOV) words, name, and
1284
+ # status of the corpus. You must use credentials for the instance of the service
1285
+ # that owns a model to list its corpora.
1286
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1287
+ # request with service credentials created for the instance of the service that owns
1288
+ # the custom model.
1289
+ # @param corpus_name [String] The name of the corpus for the custom language model. When adding a corpus, do not
1290
+ # include spaces in the name; use a localized name that matches the language of the
1291
+ # custom model; and do not use the name `user`, which is reserved by the service to
1292
+ # denote custom words added or modified by the user.
1293
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1294
+ def get_corpus(customization_id:, corpus_name:)
1295
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1296
+ raise ArgumentError("corpus_name must be provided") if corpus_name.nil?
1297
+ headers = {
1298
+ }
1299
+ method_url = "/v1/customizations/%s/corpora/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(corpus_name)]
1300
+ response = request(
1301
+ method: "GET",
1302
+ url: method_url,
1303
+ headers: headers,
1304
+ accept_json: true
1305
+ )
1306
+ response
1307
+ end
1308
+
1309
+ ##
1310
+ # @!method delete_corpus(customization_id:, corpus_name:)
1311
+ # Delete a corpus.
1312
+ # Deletes an existing corpus from a custom language model. The service removes any
1313
+ # out-of-vocabulary (OOV) words associated with the corpus from the custom model's
1314
+ # words resource unless they were also added by another corpus or they have been
1315
+ # modified in some way with the **Add custom words** or **Add a custom word**
1316
+ # method. Removing a corpus does not affect the custom model until you train the
1317
+ # model with the **Train a custom language model** method. You must use credentials
1318
+ # for the instance of the service that owns a model to delete its corpora.
1319
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1320
+ # request with service credentials created for the instance of the service that owns
1321
+ # the custom model.
1322
+ # @param corpus_name [String] The name of the corpus for the custom language model. When adding a corpus, do not
1323
+ # include spaces in the name; use a localized name that matches the language of the
1324
+ # custom model; and do not use the name `user`, which is reserved by the service to
1325
+ # denote custom words added or modified by the user.
1326
+ # @return [nil]
1327
+ def delete_corpus(customization_id:, corpus_name:)
1328
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1329
+ raise ArgumentError("corpus_name must be provided") if corpus_name.nil?
1330
+ headers = {
1331
+ }
1332
+ method_url = "/v1/customizations/%s/corpora/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(corpus_name)]
1333
+ request(
1334
+ method: "DELETE",
1335
+ url: method_url,
1336
+ headers: headers,
1337
+ accept_json: true
1338
+ )
1339
+ nil
1340
+ end
1341
+ #########################
1342
+ # Custom words
1343
+ #########################
1344
+
1345
+ ##
1346
+ # @!method list_words(customization_id:, word_type: nil, sort: nil)
1347
+ # List custom words.
1348
+ # Lists information about custom words from a custom language model. You can list
1349
+ # all words from the custom model's words resource, only custom words that were
1350
+ # added or modified by the user, or only out-of-vocabulary (OOV) words that were
1351
+ # extracted from corpora. You can also indicate the order in which the service is to
1352
+ # return words; by default, words are listed in ascending alphabetical order. You
1353
+ # must use credentials for the instance of the service that owns a model to query
1354
+ # information about its words.
1355
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1356
+ # request with service credentials created for the instance of the service that owns
1357
+ # the custom model.
1358
+ # @param word_type [String] The type of words to be listed from the custom language model's words resource:
1359
+ # * `all` (the default) shows all words.
1360
+ # * `user` shows only custom words that were added or modified by the user.
1361
+ # * `corpora` shows only OOV that were extracted from corpora.
1362
+ # @param sort [String] Indicates the order in which the words are to be listed, `alphabetical` or by
1363
+ # `count`. You can prepend an optional `+` or `-` to an argument to indicate whether
1364
+ # the results are to be sorted in ascending or descending order. By default, words
1365
+ # are sorted in ascending alphabetical order. For alphabetical ordering, the
1366
+ # lexicographical precedence is numeric values, uppercase letters, and lowercase
1367
+ # letters. For count ordering, values with the same count are ordered
1368
+ # alphabetically. With cURL, URL encode the `+` symbol as `%2B`.
1369
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1370
+ def list_words(customization_id:, word_type: nil, sort: nil)
1371
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1372
+ headers = {
1373
+ }
1374
+ params = {
1375
+ "word_type" => word_type,
1376
+ "sort" => sort
1377
+ }
1378
+ method_url = "/v1/customizations/%s/words" % [ERB::Util.url_encode(customization_id)]
1379
+ response = request(
1380
+ method: "GET",
1381
+ url: method_url,
1382
+ headers: headers,
1383
+ params: params,
1384
+ accept_json: true
1385
+ )
1386
+ response
1387
+ end
1388
+
1389
+ ##
1390
+ # @!method add_words(customization_id:, words:)
1391
+ # Add custom words.
1392
+ # Adds one or more custom words to a custom language model. The service populates
1393
+ # the words resource for a custom model with out-of-vocabulary (OOV) words found in
1394
+ # each corpus added to the model. You can use this method to add additional words or
1395
+ # to modify existing words in the words resource. The words resource for a model can
1396
+ # contain a maximum of 30 thousand custom (OOV) words, including words that the
1397
+ # service extracts from corpora and words that you add directly.
1398
+ #
1399
+ # You must use credentials for the instance of the service that owns a model to add
1400
+ # or modify custom words for the model. Adding or modifying custom words does not
1401
+ # affect the custom model until you train the model for the new data by using the
1402
+ # **Train a custom language model** method.
1403
+ #
1404
+ # You add custom words by providing a `CustomWords` object, which is an array of
1405
+ # `CustomWord` objects, one per word. You must use the object's `word` parameter to
1406
+ # identify the word that is to be added. You can also provide one or both of the
1407
+ # optional `sounds_like` and `display_as` fields for each word.
1408
+ # * The `sounds_like` field provides an array of one or more pronunciations for the
1409
+ # word. Use the parameter to specify how the word can be pronounced by users. Use
1410
+ # the parameter for words that are difficult to pronounce, foreign words, acronyms,
1411
+ # and so on. For example, you might specify that the word `IEEE` can sound like `i
1412
+ # triple e`. You can specify a maximum of five sounds-like pronunciations for a
1413
+ # word. For information about pronunciation rules, see [Using the sounds_like
1414
+ # field](https://console.bluemix.net/docs/services/speech-to-text/language-resource.html#soundsLike).
1415
+ # * The `display_as` field provides a different way of spelling the word in a
1416
+ # transcript. Use the parameter when you want the word to appear different from its
1417
+ # usual representation or from its spelling in corpora training data. For example,
1418
+ # you might indicate that the word `IBM(trademark)` is to be displayed as
1419
+ # `IBM&trade;`. For more information, see [Using the display_as
1420
+ # field](https://console.bluemix.net/docs/services/speech-to-text/language-resource.html#displayAs).
1421
+ #
1422
+ #
1423
+ # If you add a custom word that already exists in the words resource for the custom
1424
+ # model, the new definition overwrites the existing data for the word. If the
1425
+ # service encounters an error with the input data, it returns a failure code and
1426
+ # does not add any of the words to the words resource.
1427
+ #
1428
+ # The call returns an HTTP 201 response code if the input data is valid. It then
1429
+ # asynchronously processes the words to add them to the model's words resource. The
1430
+ # time that it takes for the analysis to complete depends on the number of new words
1431
+ # that you add but is generally faster than adding a corpus or training a model.
1432
+ #
1433
+ # You can monitor the status of the request by using the **List a custom language
1434
+ # model** method to poll the model's status. Use a loop to check the status every 10
1435
+ # seconds. The method returns a `Customization` object that includes a `status`
1436
+ # field. A status of `ready` means that the words have been added to the custom
1437
+ # model. The service cannot accept requests to add new corpora or words or to train
1438
+ # the model until the existing request completes.
1439
+ #
1440
+ # You can use the **List custom words** or **List a custom word** method to review
1441
+ # the words that you add. Words with an invalid `sounds_like` field include an
1442
+ # `error` field that describes the problem. You can use other words-related methods
1443
+ # to correct errors, eliminate typos, and modify how words are pronounced as needed.
1444
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1445
+ # request with service credentials created for the instance of the service that owns
1446
+ # the custom model.
1447
+ # @param words [Array[CustomWord]] An array of objects that provides information about each custom word that is to be
1448
+ # added to or updated in the custom language model.
1449
+ # @return [nil]
1450
+ def add_words(customization_id:, words:)
1451
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1452
+ raise ArgumentError("words must be provided") if words.nil?
1453
+ headers = {
1454
+ }
1455
+ data = {
1456
+ "words" => words
1457
+ }
1458
+ method_url = "/v1/customizations/%s/words" % [ERB::Util.url_encode(customization_id)]
1459
+ request(
1460
+ method: "POST",
1461
+ url: method_url,
1462
+ headers: headers,
1463
+ json: data,
1464
+ accept_json: true
1465
+ )
1466
+ nil
1467
+ end
1468
+
1469
+ ##
1470
+ # @!method add_word(customization_id:, word_name:, word: nil, sounds_like: nil, display_as: nil)
1471
+ # Add a custom word.
1472
+ # Adds a custom word to a custom language model. The service populates the words
1473
+ # resource for a custom model with out-of-vocabulary (OOV) words found in each
1474
+ # corpus added to the model. You can use this method to add a word or to modify an
1475
+ # existing word in the words resource. The words resource for a model can contain a
1476
+ # maximum of 30 thousand custom (OOV) words, including words that the service
1477
+ # extracts from corpora and words that you add directly.
1478
+ #
1479
+ # You must use credentials for the instance of the service that owns a model to add
1480
+ # or modify a custom word for the model. Adding or modifying a custom word does not
1481
+ # affect the custom model until you train the model for the new data by using the
1482
+ # **Train a custom language model** method.
1483
+ #
1484
+ # Use the `word_name` parameter to specify the custom word that is to be added or
1485
+ # modified. Use the `CustomWord` object to provide one or both of the optional
1486
+ # `sounds_like` and `display_as` fields for the word.
1487
+ # * The `sounds_like` field provides an array of one or more pronunciations for the
1488
+ # word. Use the parameter to specify how the word can be pronounced by users. Use
1489
+ # the parameter for words that are difficult to pronounce, foreign words, acronyms,
1490
+ # and so on. For example, you might specify that the word `IEEE` can sound like `i
1491
+ # triple e`. You can specify a maximum of five sounds-like pronunciations for a
1492
+ # word. For information about pronunciation rules, see [Using the sounds_like
1493
+ # field](https://console.bluemix.net/docs/services/speech-to-text/language-resource.html#soundsLike).
1494
+ # * The `display_as` field provides a different way of spelling the word in a
1495
+ # transcript. Use the parameter when you want the word to appear different from its
1496
+ # usual representation or from its spelling in corpora training data. For example,
1497
+ # you might indicate that the word `IBM(trademark)` is to be displayed as
1498
+ # `IBM&trade;`. For more information, see [Using the display_as
1499
+ # field](https://console.bluemix.net/docs/services/speech-to-text/language-resource.html#displayAs).
1500
+ #
1501
+ #
1502
+ # If you add a custom word that already exists in the words resource for the custom
1503
+ # model, the new definition overwrites the existing data for the word. If the
1504
+ # service encounters an error, it does not add the word to the words resource. Use
1505
+ # the **List a custom word** method to review the word that you add.
1506
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1507
+ # request with service credentials created for the instance of the service that owns
1508
+ # the custom model.
1509
+ # @param word_name [String] The custom word for the custom language model. When you add or update a custom
1510
+ # word with the **Add a custom word** method, do not include spaces in the word. Use
1511
+ # a `-` (dash) or `_` (underscore) to connect the tokens of compound words.
1512
+ # @param word [String] For the **Add custom words** method, you must specify the custom word that is to
1513
+ # be added to or updated in the custom model. Do not include spaces in the word. Use
1514
+ # a `-` (dash) or `_` (underscore) to connect the tokens of compound words.
1515
+ #
1516
+ # Omit this field for the **Add a custom word** method.
1517
+ # @param sounds_like [Array[String]] An array of sounds-like pronunciations for the custom word. Specify how words that
1518
+ # are difficult to pronounce, foreign words, acronyms, and so on can be pronounced
1519
+ # by users. For a word that is not in the service's base vocabulary, omit the
1520
+ # parameter to have the service automatically generate a sounds-like pronunciation
1521
+ # for the word. For a word that is in the service's base vocabulary, use the
1522
+ # parameter to specify additional pronunciations for the word. You cannot override
1523
+ # the default pronunciation of a word; pronunciations you add augment the
1524
+ # pronunciation from the base vocabulary. A word can have at most five sounds-like
1525
+ # pronunciations, and a pronunciation can include at most 40 characters not
1526
+ # including spaces.
1527
+ # @param display_as [String] An alternative spelling for the custom word when it appears in a transcript. Use
1528
+ # the parameter when you want the word to have a spelling that is different from its
1529
+ # usual representation or from its spelling in corpora training data.
1530
+ # @return [nil]
1531
+ def add_word(customization_id:, word_name:, word: nil, sounds_like: nil, display_as: nil)
1532
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1533
+ raise ArgumentError("word_name must be provided") if word_name.nil?
1534
+ headers = {
1535
+ }
1536
+ data = {
1537
+ "word" => word,
1538
+ "sounds_like" => sounds_like,
1539
+ "display_as" => display_as
1540
+ }
1541
+ method_url = "/v1/customizations/%s/words/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(word_name)]
1542
+ request(
1543
+ method: "PUT",
1544
+ url: method_url,
1545
+ headers: headers,
1546
+ json: data,
1547
+ accept_json: true
1548
+ )
1549
+ nil
1550
+ end
1551
+
1552
+ ##
1553
+ # @!method get_word(customization_id:, word_name:)
1554
+ # Get a custom word.
1555
+ # Gets information about a custom word from a custom language model. You must use
1556
+ # credentials for the instance of the service that owns a model to query information
1557
+ # about its words.
1558
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1559
+ # request with service credentials created for the instance of the service that owns
1560
+ # the custom model.
1561
+ # @param word_name [String] The custom word for the custom language model. When you add or update a custom
1562
+ # word with the **Add a custom word** method, do not include spaces in the word. Use
1563
+ # a `-` (dash) or `_` (underscore) to connect the tokens of compound words.
1564
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1565
+ def get_word(customization_id:, word_name:)
1566
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1567
+ raise ArgumentError("word_name must be provided") if word_name.nil?
1568
+ headers = {
1569
+ }
1570
+ method_url = "/v1/customizations/%s/words/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(word_name)]
1571
+ response = request(
1572
+ method: "GET",
1573
+ url: method_url,
1574
+ headers: headers,
1575
+ accept_json: true
1576
+ )
1577
+ response
1578
+ end
1579
+
1580
+ ##
1581
+ # @!method delete_word(customization_id:, word_name:)
1582
+ # Delete a custom word.
1583
+ # Deletes a custom word from a custom language model. You can remove any word that
1584
+ # you added to the custom model's words resource via any means. However, if the word
1585
+ # also exists in the service's base vocabulary, the service removes only the custom
1586
+ # pronunciation for the word; the word remains in the base vocabulary. Removing a
1587
+ # custom word does not affect the custom model until you train the model with the
1588
+ # **Train a custom language model** method. You must use credentials for the
1589
+ # instance of the service that owns a model to delete its words.
1590
+ # @param customization_id [String] The customization ID (GUID) of the custom language model. You must make the
1591
+ # request with service credentials created for the instance of the service that owns
1592
+ # the custom model.
1593
+ # @param word_name [String] The custom word for the custom language model. When you add or update a custom
1594
+ # word with the **Add a custom word** method, do not include spaces in the word. Use
1595
+ # a `-` (dash) or `_` (underscore) to connect the tokens of compound words.
1596
+ # @return [nil]
1597
+ def delete_word(customization_id:, word_name:)
1598
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1599
+ raise ArgumentError("word_name must be provided") if word_name.nil?
1600
+ headers = {
1601
+ }
1602
+ method_url = "/v1/customizations/%s/words/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(word_name)]
1603
+ request(
1604
+ method: "DELETE",
1605
+ url: method_url,
1606
+ headers: headers,
1607
+ accept_json: true
1608
+ )
1609
+ nil
1610
+ end
1611
+ #########################
1612
+ # Custom acoustic models
1613
+ #########################
1614
+
1615
+ ##
1616
+ # @!method create_acoustic_model(name:, base_model_name:, description: nil)
1617
+ # Create a custom acoustic model.
1618
+ # Creates a new custom acoustic model for a specified base model. The custom
1619
+ # acoustic model can be used only with the base model for which it is created. The
1620
+ # model is owned by the instance of the service whose credentials are used to create
1621
+ # it.
1622
+ # @param name [String] A user-defined name for the new custom acoustic model. Use a name that is unique
1623
+ # among all custom acoustic models that you own. Use a localized name that matches
1624
+ # the language of the custom model. Use a name that describes the acoustic
1625
+ # environment of the custom model, such as `Mobile custom model` or `Noisy car
1626
+ # custom model`.
1627
+ # @param base_model_name [String] The name of the base language model that is to be customized by the new custom
1628
+ # acoustic model. The new custom model can be used only with the base model that it
1629
+ # customizes. To determine whether a base model supports acoustic model
1630
+ # customization, refer to [Language support for
1631
+ # customization](https://console.bluemix.net/docs/services/speech-to-text/custom.html#languageSupport).
1632
+ # @param description [String] A description of the new custom acoustic model. Use a localized description that
1633
+ # matches the language of the custom model.
1634
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1635
+ def create_acoustic_model(name:, base_model_name:, description: nil)
1636
+ raise ArgumentError("name must be provided") if name.nil?
1637
+ raise ArgumentError("base_model_name must be provided") if base_model_name.nil?
1638
+ headers = {
1639
+ }
1640
+ data = {
1641
+ "name" => name,
1642
+ "base_model_name" => base_model_name,
1643
+ "description" => description
1644
+ }
1645
+ method_url = "/v1/acoustic_customizations"
1646
+ response = request(
1647
+ method: "POST",
1648
+ url: method_url,
1649
+ headers: headers,
1650
+ json: data,
1651
+ accept_json: true
1652
+ )
1653
+ response
1654
+ end
1655
+
1656
+ ##
1657
+ # @!method list_acoustic_models(language: nil)
1658
+ # List custom acoustic models.
1659
+ # Lists information about all custom acoustic models that are owned by an instance
1660
+ # of the service. Use the `language` parameter to see all custom acoustic models for
1661
+ # the specified language. Omit the parameter to see all custom acoustic models for
1662
+ # all languages. You must use credentials for the instance of the service that owns
1663
+ # a model to list information about it.
1664
+ # @param language [String] The identifier of the language for which custom language or custom acoustic models
1665
+ # are to be returned (for example, `en-US`). Omit the parameter to see all custom
1666
+ # language or custom acoustic models owned by the requesting service credentials.
1667
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1668
+ def list_acoustic_models(language: nil)
1669
+ headers = {
1670
+ }
1671
+ params = {
1672
+ "language" => language
1673
+ }
1674
+ method_url = "/v1/acoustic_customizations"
1675
+ response = request(
1676
+ method: "GET",
1677
+ url: method_url,
1678
+ headers: headers,
1679
+ params: params,
1680
+ accept_json: true
1681
+ )
1682
+ response
1683
+ end
1684
+
1685
+ ##
1686
+ # @!method get_acoustic_model(customization_id:)
1687
+ # Get a custom acoustic model.
1688
+ # Gets information about a specified custom acoustic model. You must use credentials
1689
+ # for the instance of the service that owns a model to list information about it.
1690
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
1691
+ # request with service credentials created for the instance of the service that owns
1692
+ # the custom model.
1693
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1694
+ def get_acoustic_model(customization_id:)
1695
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1696
+ headers = {
1697
+ }
1698
+ method_url = "/v1/acoustic_customizations/%s" % [ERB::Util.url_encode(customization_id)]
1699
+ response = request(
1700
+ method: "GET",
1701
+ url: method_url,
1702
+ headers: headers,
1703
+ accept_json: true
1704
+ )
1705
+ response
1706
+ end
1707
+
1708
+ ##
1709
+ # @!method delete_acoustic_model(customization_id:)
1710
+ # Delete a custom acoustic model.
1711
+ # Deletes an existing custom acoustic model. The custom model cannot be deleted if
1712
+ # another request, such as adding an audio resource to the model, is currently being
1713
+ # processed. You must use credentials for the instance of the service that owns a
1714
+ # model to delete it.
1715
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
1716
+ # request with service credentials created for the instance of the service that owns
1717
+ # the custom model.
1718
+ # @return [nil]
1719
+ def delete_acoustic_model(customization_id:)
1720
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1721
+ headers = {
1722
+ }
1723
+ method_url = "/v1/acoustic_customizations/%s" % [ERB::Util.url_encode(customization_id)]
1724
+ request(
1725
+ method: "DELETE",
1726
+ url: method_url,
1727
+ headers: headers,
1728
+ accept_json: true
1729
+ )
1730
+ nil
1731
+ end
1732
+
1733
+ ##
1734
+ # @!method train_acoustic_model(customization_id:, custom_language_model_id: nil)
1735
+ # Train a custom acoustic model.
1736
+ # Initiates the training of a custom acoustic model with new or changed audio
1737
+ # resources. After adding or deleting audio resources for a custom acoustic model,
1738
+ # use this method to begin the actual training of the model on the latest audio
1739
+ # data. The custom acoustic model does not reflect its changed data until you train
1740
+ # it. You must use credentials for the instance of the service that owns a model to
1741
+ # train it.
1742
+ #
1743
+ # The training method is asynchronous. It can take on the order of minutes or hours
1744
+ # to complete depending on the total amount of audio data on which the custom
1745
+ # acoustic model is being trained and the current load on the service. Typically,
1746
+ # training a custom acoustic model takes approximately two to four times the length
1747
+ # of its audio data. The range of time depends on the model being trained and the
1748
+ # nature of the audio, such as whether the audio is clean or noisy. The method
1749
+ # returns an HTTP 200 response code to indicate that the training process has begun.
1750
+ #
1751
+ #
1752
+ # You can monitor the status of the training by using the **Get a custom acoustic
1753
+ # model** method to poll the model's status. Use a loop to check the status once a
1754
+ # minute. The method returns an `AcousticModel` object that includes `status` and
1755
+ # `progress` fields. A status of `available` indicates that the custom model is
1756
+ # trained and ready to use. The service cannot accept subsequent training requests,
1757
+ # or requests to add new audio resources, until the existing request completes.
1758
+ #
1759
+ # You can use the optional `custom_language_model_id` parameter to specify the GUID
1760
+ # of a separately created custom language model that is to be used during training.
1761
+ # Specify a custom language model if you have verbatim transcriptions of the audio
1762
+ # files that you have added to the custom model or you have either corpora (text
1763
+ # files) or a list of words that are relevant to the contents of the audio files.
1764
+ # For information about creating a separate custom language model, see [Creating a
1765
+ # custom language
1766
+ # model](https://console.bluemix.net/docs/services/speech-to-text/language-create.html).
1767
+ #
1768
+ #
1769
+ # Training can fail to start for the following reasons:
1770
+ # * The service is currently handling another request for the custom model, such as
1771
+ # another training request or a request to add audio resources to the model.
1772
+ # * The custom model contains less than 10 minutes or more than 50 hours of audio
1773
+ # data.
1774
+ # * One or more of the custom model's audio resources is invalid.
1775
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
1776
+ # request with service credentials created for the instance of the service that owns
1777
+ # the custom model.
1778
+ # @param custom_language_model_id [String] The customization ID (GUID) of a custom language model that is to be used during
1779
+ # training of the custom acoustic model. Specify a custom language model that has
1780
+ # been trained with verbatim transcriptions of the audio resources or that contains
1781
+ # words that are relevant to the contents of the audio resources.
1782
+ # @return [nil]
1783
+ def train_acoustic_model(customization_id:, custom_language_model_id: nil)
1784
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1785
+ headers = {
1786
+ }
1787
+ params = {
1788
+ "custom_language_model_id" => custom_language_model_id
1789
+ }
1790
+ method_url = "/v1/acoustic_customizations/%s/train" % [ERB::Util.url_encode(customization_id)]
1791
+ request(
1792
+ method: "POST",
1793
+ url: method_url,
1794
+ headers: headers,
1795
+ params: params,
1796
+ accept_json: true
1797
+ )
1798
+ nil
1799
+ end
1800
+
1801
+ ##
1802
+ # @!method reset_acoustic_model(customization_id:)
1803
+ # Reset a custom acoustic model.
1804
+ # Resets a custom acoustic model by removing all audio resources from the model.
1805
+ # Resetting a custom acoustic model initializes the model to its state when it was
1806
+ # first created. Metadata such as the name and language of the model are preserved,
1807
+ # but the model's audio resources are removed and must be re-created. You must use
1808
+ # credentials for the instance of the service that owns a model to reset it.
1809
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
1810
+ # request with service credentials created for the instance of the service that owns
1811
+ # the custom model.
1812
+ # @return [nil]
1813
+ def reset_acoustic_model(customization_id:)
1814
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1815
+ headers = {
1816
+ }
1817
+ method_url = "/v1/acoustic_customizations/%s/reset" % [ERB::Util.url_encode(customization_id)]
1818
+ request(
1819
+ method: "POST",
1820
+ url: method_url,
1821
+ headers: headers,
1822
+ accept_json: true
1823
+ )
1824
+ nil
1825
+ end
1826
+
1827
+ ##
1828
+ # @!method upgrade_acoustic_model(customization_id:, custom_language_model_id: nil)
1829
+ # Upgrade a custom acoustic model.
1830
+ # Initiates the upgrade of a custom acoustic model to the latest version of its base
1831
+ # language model. The upgrade method is asynchronous. It can take on the order of
1832
+ # minutes or hours to complete depending on the amount of data in the custom model
1833
+ # and the current load on the service; typically, upgrade takes approximately twice
1834
+ # the length of the total audio contained in the custom model. A custom model must
1835
+ # be in the `ready` or `available` state to be upgraded. You must use credentials
1836
+ # for the instance of the service that owns a model to upgrade it.
1837
+ #
1838
+ # The method returns an HTTP 200 response code to indicate that the upgrade process
1839
+ # has begun successfully. You can monitor the status of the upgrade by using the
1840
+ # **Get a custom acoustic model** method to poll the model's status. The method
1841
+ # returns an `AcousticModel` object that includes `status` and `progress` fields.
1842
+ # Use a loop to check the status once a minute. While it is being upgraded, the
1843
+ # custom model has the status `upgrading`. When the upgrade is complete, the model
1844
+ # resumes the status that it had prior to upgrade. The service cannot accept
1845
+ # subsequent requests for the model until the upgrade completes.
1846
+ #
1847
+ # If the custom acoustic model was trained with a separately created custom language
1848
+ # model, you must use the `custom_language_model_id` parameter to specify the GUID
1849
+ # of that custom language model. The custom language model must be upgraded before
1850
+ # the custom acoustic model can be upgraded. Omit the parameter if the custom
1851
+ # acoustic model was not trained with a custom language model.
1852
+ #
1853
+ # For more information, see [Upgrading custom
1854
+ # models](https://console.bluemix.net/docs/services/speech-to-text/custom-upgrade.html).
1855
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
1856
+ # request with service credentials created for the instance of the service that owns
1857
+ # the custom model.
1858
+ # @param custom_language_model_id [String] If the custom acoustic model was trained with a custom language model, the
1859
+ # customization ID (GUID) of that custom language model. The custom language model
1860
+ # must be upgraded before the custom acoustic model can be upgraded.
1861
+ # @return [nil]
1862
+ def upgrade_acoustic_model(customization_id:, custom_language_model_id: nil)
1863
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1864
+ headers = {
1865
+ }
1866
+ params = {
1867
+ "custom_language_model_id" => custom_language_model_id
1868
+ }
1869
+ method_url = "/v1/acoustic_customizations/%s/upgrade_model" % [ERB::Util.url_encode(customization_id)]
1870
+ request(
1871
+ method: "POST",
1872
+ url: method_url,
1873
+ headers: headers,
1874
+ params: params,
1875
+ accept_json: true
1876
+ )
1877
+ nil
1878
+ end
1879
+ #########################
1880
+ # Custom audio resources
1881
+ #########################
1882
+
1883
+ ##
1884
+ # @!method list_audio(customization_id:)
1885
+ # List audio resources.
1886
+ # Lists information about all audio resources from a custom acoustic model. The
1887
+ # information includes the name of the resource and information about its audio
1888
+ # data, such as its duration. It also includes the status of the audio resource,
1889
+ # which is important for checking the service's analysis of the resource in response
1890
+ # to a request to add it to the custom acoustic model. You must use credentials for
1891
+ # the instance of the service that owns a model to list its audio resources.
1892
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
1893
+ # request with service credentials created for the instance of the service that owns
1894
+ # the custom model.
1895
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1896
+ def list_audio(customization_id:)
1897
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
1898
+ headers = {
1899
+ }
1900
+ method_url = "/v1/acoustic_customizations/%s/audio" % [ERB::Util.url_encode(customization_id)]
1901
+ response = request(
1902
+ method: "GET",
1903
+ url: method_url,
1904
+ headers: headers,
1905
+ accept_json: true
1906
+ )
1907
+ response
1908
+ end
1909
+
1910
+ ##
1911
+ # @!method add_audio(customization_id:, audio_name:, audio_resource:, content_type:, contained_content_type: nil, allow_overwrite: nil)
1912
+ # Add an audio resource.
1913
+ # Adds an audio resource to a custom acoustic model. Add audio content that reflects
1914
+ # the acoustic characteristics of the audio that you plan to transcribe. You must
1915
+ # use credentials for the instance of the service that owns a model to add an audio
1916
+ # resource to it. Adding audio data does not affect the custom acoustic model until
1917
+ # you train the model for the new data by using the **Train a custom acoustic
1918
+ # model** method.
1919
+ #
1920
+ # You can add individual audio files or an archive file that contains multiple audio
1921
+ # files. Adding multiple audio files via a single archive file is significantly more
1922
+ # efficient than adding each file individually. You can add audio resources in any
1923
+ # format that the service supports for speech recognition.
1924
+ #
1925
+ # You can use this method to add any number of audio resources to a custom model by
1926
+ # calling the method once for each audio or archive file. But the addition of one
1927
+ # audio resource must be fully complete before you can add another. You must add a
1928
+ # minimum of 10 minutes and a maximum of 50 hours of audio that includes speech, not
1929
+ # just silence, to a custom acoustic model before you can train it. No audio
1930
+ # resource, audio- or archive-type, can be larger than 100 MB. To add an audio
1931
+ # resource that has the same name as an existing audio resource, set the
1932
+ # `allow_overwrite` parameter to `true`; otherwise, the request fails.
1933
+ #
1934
+ # The method is asynchronous. It can take several seconds to complete depending on
1935
+ # the duration of the audio and, in the case of an archive file, the total number of
1936
+ # audio files being processed. The service returns a 201 response code if the audio
1937
+ # is valid. It then asynchronously analyzes the contents of the audio file or files
1938
+ # and automatically extracts information about the audio such as its length,
1939
+ # sampling rate, and encoding. You cannot submit requests to add additional audio
1940
+ # resources to a custom acoustic model, or to train the model, until the service's
1941
+ # analysis of all audio files for the current request completes.
1942
+ #
1943
+ # To determine the status of the service's analysis of the audio, use the **Get an
1944
+ # audio resource** method to poll the status of the audio. The method accepts the
1945
+ # customization ID of the custom model and the name of the audio resource, and it
1946
+ # returns the status of the resource. Use a loop to check the status of the audio
1947
+ # every few seconds until it becomes `ok`.
1948
+ #
1949
+ # ### Content types for audio-type resources
1950
+ #
1951
+ # You can add an individual audio file in any format that the service supports for
1952
+ # speech recognition. For an audio-type resource, use the `Content-Type` parameter
1953
+ # to specify the audio format (MIME type) of the audio file:
1954
+ # * `audio/basic` (Use only with narrowband models.)
1955
+ # * `audio/flac`
1956
+ # * `audio/l16` (Specify the sampling rate (`rate`) and optionally the number of
1957
+ # channels (`channels`) and endianness (`endianness`) of the audio.)
1958
+ # * `audio/mp3`
1959
+ # * `audio/mpeg`
1960
+ # * `audio/mulaw` (Specify the sampling rate (`rate`) of the audio.)
1961
+ # * `audio/ogg` (The service automatically detects the codec of the input audio.)
1962
+ # * `audio/ogg;codecs=opus`
1963
+ # * `audio/ogg;codecs=vorbis`
1964
+ # * `audio/wav` (Provide audio with a maximum of nine channels.)
1965
+ # * `audio/webm` (The service automatically detects the codec of the input audio.)
1966
+ # * `audio/webm;codecs=opus`
1967
+ # * `audio/webm;codecs=vorbis`
1968
+ #
1969
+ # For information about the supported audio formats, including specifying the
1970
+ # sampling rate, channels, and endianness for the indicated formats, see [Audio
1971
+ # formats](https://console.bluemix.net/docs/services/speech-to-text/audio-formats.html).
1972
+ #
1973
+ #
1974
+ # **Note:** The sampling rate of an audio file must match the sampling rate of the
1975
+ # base model for the custom model: for broadband models, at least 16 kHz; for
1976
+ # narrowband models, at least 8 kHz. If the sampling rate of the audio is higher
1977
+ # than the minimum required rate, the service down-samples the audio to the
1978
+ # appropriate rate. If the sampling rate of the audio is lower than the minimum
1979
+ # required rate, the service labels the audio file as `invalid`.
1980
+ #
1981
+ # ### Content types for archive-type resources
1982
+ #
1983
+ # You can add an archive file (**.zip** or **.tar.gz** file) that contains audio
1984
+ # files in any format that the service supports for speech recognition. For an
1985
+ # archive-type resource, use the `Content-Type` parameter to specify the media type
1986
+ # of the archive file:
1987
+ # * `application/zip` for a **.zip** file
1988
+ # * `application/gzip` for a **.tar.gz** file.
1989
+ #
1990
+ # All audio files contained in the archive must have the same audio format. Use the
1991
+ # `Contained-Content-Type` parameter to specify the format of the contained audio
1992
+ # files. The parameter accepts all of the audio formats supported for use with
1993
+ # speech recognition and with the `Content-Type` header, including the `rate`,
1994
+ # `channels`, and `endianness` parameters that are used with some formats. The
1995
+ # default contained audio format is `audio/wav`.
1996
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
1997
+ # request with service credentials created for the instance of the service that owns
1998
+ # the custom model.
1999
+ # @param audio_name [String] The name of the audio resource for the custom acoustic model. When adding an audio
2000
+ # resource, do not include spaces in the name; use a localized name that matches the
2001
+ # language of the custom model.
2002
+ # @param audio_resource [Array[String]] The audio resource that is to be added to the custom acoustic model, an individual
2003
+ # audio file or an archive file.
2004
+ # @param content_type [String] The type of the input.
2005
+ # @param contained_content_type [String] For an archive-type resource, specifies the format of the audio files contained in
2006
+ # the archive file. The parameter accepts all of the audio formats supported for use
2007
+ # with speech recognition, including the `rate`, `channels`, and `endianness`
2008
+ # parameters that are used with some formats. For a complete list of supported audio
2009
+ # formats, see [Audio formats](/docs/services/speech-to-text/input.html#formats).
2010
+ # @param allow_overwrite [Boolean] If `true`, the specified corpus or audio resource overwrites an existing corpus or
2011
+ # audio resource with the same name. If `false` (the default), the request fails if
2012
+ # a corpus or audio resource with the same name already exists. The parameter has no
2013
+ # effect if a corpus or audio resource with the same name does not already exist.
2014
+ # @return [nil]
2015
+ def add_audio(customization_id:, audio_name:, audio_resource:, content_type:, contained_content_type: nil, allow_overwrite: nil)
2016
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
2017
+ raise ArgumentError("audio_name must be provided") if audio_name.nil?
2018
+ raise ArgumentError("audio_resource must be provided") if audio_resource.nil?
2019
+ raise ArgumentError("content_type must be provided") if content_type.nil?
2020
+ headers = {
2021
+ "Content-Type" => content_type,
2022
+ "Contained-Content-Type" => contained_content_type
2023
+ }
2024
+ params = {
2025
+ "allow_overwrite" => allow_overwrite
2026
+ }
2027
+ data = audio_resource
2028
+ method_url = "/v1/acoustic_customizations/%s/audio/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(audio_name)]
2029
+ request(
2030
+ method: "POST",
2031
+ url: method_url,
2032
+ headers: headers,
2033
+ params: params,
2034
+ data: data,
2035
+ accept_json: true
2036
+ )
2037
+ nil
2038
+ end
2039
+
2040
+ ##
2041
+ # @!method get_audio(customization_id:, audio_name:)
2042
+ # Get an audio resource.
2043
+ # Gets information about an audio resource from a custom acoustic model. The method
2044
+ # returns an `AudioListing` object whose fields depend on the type of audio resource
2045
+ # that you specify with the method's `audio_name` parameter:
2046
+ # * **For an audio-type resource,** the object's fields match those of an
2047
+ # `AudioResource` object: `duration`, `name`, `details`, and `status`.
2048
+ # * **For an archive-type resource,** the object includes a `container` field whose
2049
+ # fields match those of an `AudioResource` object. It also includes an `audio`
2050
+ # field, which contains an array of `AudioResource` objects that provides
2051
+ # information about the audio files that are contained in the archive.
2052
+ #
2053
+ # The information includes the status of the specified audio resource. The status is
2054
+ # important for checking the service's analysis of a resource that you add to the
2055
+ # custom model.
2056
+ # * For an audio-type resource, the `status` field is located in the `AudioListing`
2057
+ # object.
2058
+ # * For an archive-type resource, the `status` field is located in the
2059
+ # `AudioResource` object that is returned in the `container` field.
2060
+ #
2061
+ # You must use credentials for the instance of the service that owns a model to list
2062
+ # its audio resources.
2063
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
2064
+ # request with service credentials created for the instance of the service that owns
2065
+ # the custom model.
2066
+ # @param audio_name [String] The name of the audio resource for the custom acoustic model. When adding an audio
2067
+ # resource, do not include spaces in the name; use a localized name that matches the
2068
+ # language of the custom model.
2069
+ # @return [DetailedResponse] A `DetailedResponse` object representing the response.
2070
+ def get_audio(customization_id:, audio_name:)
2071
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
2072
+ raise ArgumentError("audio_name must be provided") if audio_name.nil?
2073
+ headers = {
2074
+ }
2075
+ method_url = "/v1/acoustic_customizations/%s/audio/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(audio_name)]
2076
+ response = request(
2077
+ method: "GET",
2078
+ url: method_url,
2079
+ headers: headers,
2080
+ accept_json: true
2081
+ )
2082
+ response
2083
+ end
2084
+
2085
+ ##
2086
+ # @!method delete_audio(customization_id:, audio_name:)
2087
+ # Delete an audio resource.
2088
+ # Deletes an existing audio resource from a custom acoustic model. Deleting an
2089
+ # archive-type audio resource removes the entire archive of files; the current
2090
+ # interface does not allow deletion of individual files from an archive resource.
2091
+ # Removing an audio resource does not affect the custom model until you train the
2092
+ # model on its updated data by using the **Train a custom acoustic model** method.
2093
+ # You must use credentials for the instance of the service that owns a model to
2094
+ # delete its audio resources.
2095
+ # @param customization_id [String] The customization ID (GUID) of the custom acoustic model. You must make the
2096
+ # request with service credentials created for the instance of the service that owns
2097
+ # the custom model.
2098
+ # @param audio_name [String] The name of the audio resource for the custom acoustic model. When adding an audio
2099
+ # resource, do not include spaces in the name; use a localized name that matches the
2100
+ # language of the custom model.
2101
+ # @return [nil]
2102
+ def delete_audio(customization_id:, audio_name:)
2103
+ raise ArgumentError("customization_id must be provided") if customization_id.nil?
2104
+ raise ArgumentError("audio_name must be provided") if audio_name.nil?
2105
+ headers = {
2106
+ }
2107
+ method_url = "/v1/acoustic_customizations/%s/audio/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(audio_name)]
2108
+ request(
2109
+ method: "DELETE",
2110
+ url: method_url,
2111
+ headers: headers,
2112
+ accept_json: true
2113
+ )
2114
+ nil
2115
+ end
2116
+ #########################
2117
+ # User data
2118
+ #########################
2119
+
2120
+ ##
2121
+ # @!method delete_user_data(customer_id:)
2122
+ # Delete labeled data.
2123
+ # Deletes all data that is associated with a specified customer ID. The method
2124
+ # deletes all data for the customer ID, regardless of the method by which the
2125
+ # information was added. The method has no effect if no data is associated with the
2126
+ # customer ID. You must issue the request with credentials for the same instance of
2127
+ # the service that was used to associate the customer ID with the data.
2128
+ #
2129
+ # You associate a customer ID with data by passing the `X-Watson-Metadata` header
2130
+ # with a request that passes the data. For more information about customer IDs and
2131
+ # about using this method, see [Information
2132
+ # security](https://console.bluemix.net/docs/services/speech-to-text/information-security.html).
2133
+ # @param customer_id [String] The customer ID for which all data is to be deleted.
2134
+ # @return [nil]
2135
+ def delete_user_data(customer_id:)
2136
+ raise ArgumentError("customer_id must be provided") if customer_id.nil?
2137
+ headers = {
2138
+ }
2139
+ params = {
2140
+ "customer_id" => customer_id
2141
+ }
2142
+ method_url = "/v1/user_data"
2143
+ request(
2144
+ method: "DELETE",
2145
+ url: method_url,
2146
+ headers: headers,
2147
+ params: params,
2148
+ accept_json: true
2149
+ )
2150
+ nil
2151
+ end
2152
+ end
2153
+ end