Introduction

The IBM Watson™ Speech to Text service provides APIs that use IBM's speech-recognition capabilities to produce transcripts of spoken audio. The service can transcribe speech from various languages and audio formats. In addition to basic transcription, the service can produce detailed information about many different aspects of the audio. It returns all JSON response content in the UTF-8 character set.

The service supports three types of models: large speech models that use the locale (ex.: en-US, fr-FR) as their name, previous-generation models that include the terms Broadband and Narrowband in their names, and next-generation models that include the terms Multimedia and Telephony in their names. Broadband and multimedia models have minimum sampling rates of 16 kHz. Narrowband and telephony models have minimum sampling rates of 8 kHz. The large speech models and next-generation models offer high throughput and greater transcription accuracy.

Effective 31 July 2023, all previous-generation models will be removed from the service and the documentation. Most previous-generation models were deprecated on 15 March 2022. You must migrate to the equivalent large speech model or next-generation model by 31 July 2023. For more information, see Migrating to large speech models.

For speech recognition, the service supports synchronous and asynchronous HTTP Representational State Transfer (REST) interfaces. It also supports a WebSocket interface that provides a full-duplex, low-latency communication channel: Clients send requests and audio to the service and receive results over a single connection asynchronously.

The service also offers two customization interfaces. Use language model customization to expand the vocabulary of a base model with domain-specific terminology. Use acoustic model customization to adapt a base model for the acoustic characteristics of your audio. For language model customization, the service also supports grammars. A grammar is a formal language specification that lets you restrict the phrases that the service can recognize.

Language model customization is available for most large speech models, previous- and next-generation models. Acoustic model customization is available for all previous-generation models.

This documentation describes Java SDK major version 9. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Node SDK major version 6. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Python SDK major version 5. For more information about how to update your code from the previous version, see the migration guide.

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.watson</groupId>
  <artifactId>ibm-watson</artifactId>
  <version>11.0.0</version>
</dependency>

Gradle

compile 'com.ibm.watson:ibm-watson:11.0.0'

GitHub

https://github.com/watson-developer-cloud/java-sdk

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-watson@^8.0.0

GitHub

https://github.com/watson-developer-cloud/node-sdk

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade "ibm-watson>=7.0.0"

GitHub

https://github.com/watson-developer-cloud/python-sdk

Endpoint URLs

Identify the base URL for your service instance.

IBM Cloud URLs

The base URLs come from the service instance. To find the URL, view the service credentials by clicking the name of the service in the Resource list. Use the value of the URL. Add the method to form the complete API endpoint for your request.

The following example URL represents a Speech to Text instance that is hosted in Washington, DC:

https://api.us-east.speech-to-text.watson.cloud.ibm.com/instances/6bbda3b3-d572-45e1-8c54-22d6ed9e52c2

The following URLs represent the base URLs for Speech to Text. When you call the API, use the URL that corresponds to the location of your service instance.

Dallas: https://api.us-south.speech-to-text.watson.cloud.ibm.com
Washington, DC: https://api.us-east.speech-to-text.watson.cloud.ibm.com
Frankfurt: https://api.eu-de.speech-to-text.watson.cloud.ibm.com
Sydney: https://api.au-syd.speech-to-text.watson.cloud.ibm.com
Tokyo: https://api.jp-tok.speech-to-text.watson.cloud.ibm.com
London: https://api.eu-gb.speech-to-text.watson.cloud.ibm.com
Seoul: https://api.kr-seo.speech-to-text.watson.cloud.ibm.com

Set the correct service URL by calling the setServiceUrl() method of the service instance.

Set the correct service URL by specifying the serviceUrl parameter when you create the service instance.

Set the correct service URL by calling the set_service_url() method of the service instance.

Dallas API endpoint example for services managed on IBM Cloud

curl -X {request_method} -u "apikey:{apikey}" \
"https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}"

Your service instance might not use this URL

Default URL

https://api.us-south.speech-to-text.watson.cloud.ibm.com

Example for the Washington, DC location

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
SpeechToText speechToText = new SpeechToText(authenticator);
speechToText.setServiceUrl("https://api.us-east.speech-to-text.watson.cloud.ibm.com");

Default URL

https://api.us-south.speech-to-text.watson.cloud.ibm.com

Example for the Washington, DC location

const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const speechToText = new SpeechToTextV1({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: 'https://api.us-east.speech-to-text.watson.cloud.ibm.com',
});

Default URL

https://api.us-south.speech-to-text.watson.cloud.ibm.com

Example for the Washington, DC location

from ibm_watson import SpeechToTextV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
speech_to_text = SpeechToTextV1(
    authenticator=authenticator
)

speech_to_text.set_service_url('https://api.us-east.speech-to-text.watson.cloud.ibm.com')

Cloud Pak for Data URLs

For services installed on Cloud Pak for Data, the base URLs come from both the cluster and service instance.

You can find the base URL from the Cloud Pak for Data web client in the details page about the instance. Click the name of the service in your list of instances to see the URL.

Use that URL in your requests to Speech to Text. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the URL by calling the setServiceUrl() method of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by specifying the serviceUrl parameter when you create the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by specifying the url parameter when you create the service instance or by calling the set_url() method of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Endpoint example for Cloud Pak for Data

curl -X {request_method} -H "Authorization: Bearer {token}" \
"https://{cpd_cluster_host}/speech-to-text/{deployment_id}/instances/{instance_id}/api"

Endpoint example for Cloud Pak for Data

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("https://{cpd_cluster_host}", "{username}", "{password}");
SpeechToText speechToText = new SpeechToText(authenticator);
speechToText.setServiceUrl("https://{cpd_cluster_host}/speech-to-text/{deployment_id}/instances/{instance_id}/api");

Endpoint example for Cloud Pak for Data

const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');
const { CloudPakForDataAuthenticator } = require('ibm-watson/auth');

const speechToText = new SpeechToTextV1({
  authenticator: new CloudPakForDataAuthenticator({
    username: '{username}',
    password: '{password}',
    url: 'https://{cpd_cluster_host}',
  }),
  serviceUrl: 'https://{cpd_cluster_host}/speech-to-text/{deployment_id}/instances/{instance_id}/api',
});

Endpoint example for Cloud Pak for Data

from ibm_watson import SpeechToTextV1
from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator

authenticator = CloudPakForDataAuthenticator(
    '{username}',
    '{password}',
    'https://{cpd_cluster_host}'
)

speech_to_text = SpeechToTextV1(
    authenticator=authenticator
)

speech_to_text.set_service_url('https://{cpd_cluster_host}/speech-to-text/{deployment_id}/instances/{instance_id}/api')

Disabling SSL verification

All Watson services use Secure Sockets Layer (SSL) (or Transport Layer Security (TLS)) for secure connections between the client and server. The connection is verified against the local certificate store to ensure authentication, integrity, and confidentiality.

If you use a self-signed certificate, you need to disable SSL verification to make a successful connection.

Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if necessary, and take steps to enable SSL as soon as possible.

To disable SSL verification for a curl request, use the --insecure (-k) option with the request.

Example to disable SSL verification with a service managed on IBM Cloud. Replace {apikey} and {url} with your service credentials.

curl -k -X {request_method} -u "apikey:{apikey}" "{url}/{method}"

To disable SSL verification, create an HttpConfigOptions object and set the disableSslVerification property to true. Then, pass the object to the service instance by using the configureClient method.

Example to disable SSL verification with a service managed on IBM Cloud

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
SpeechToText speechToText = new SpeechToText(authenticator);
speechToText.setServiceUrl("{url}");

HttpConfigOptions configOptions = new HttpConfigOptions.Builder()
  .disableSslVerification(true)
  .build();
speechToText.configureClient(configOptions);

To disable SSL verification, set the disableSslVerification parameter to true when you create the service instance.

Example to disable SSL verification with a service managed on IBM Cloud

const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const speechToText = new SpeechToTextV1({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
  disableSslVerification: true,
});

To disable SSL verification, specify True on the set_disable_ssl_verification method for the service instance.

Example to disable SSL verification with a service managed on IBM Cloud

from ibm_watson import SpeechToTextV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
speech_to_text = SpeechToTextV1(
    authenticator=authenticator
)

speech_to_text.set_service_url('{url}')

speech_to_text.set_disable_ssl_verification(True)

Example to disable SSL verification with an installed service

curl -k -X {request_method} -H "Authorization: Bearer {token}" \
"{url}/v1/{method}"

Example to disable SSL verification with an installed service

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("https://{cpd_cluster_host}", "{username}", "{password}");
SpeechToText speechToText = new SpeechToText(authenticator);
speechToText.setServiceUrl("{url}";

HttpConfigOptions configOptions = new HttpConfigOptions.Builder()
  .disableSslVerification(true)
  .build();
speechToText.configureClient(configOptions);

Example to disable SSL verification with an installed service

const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');
const { CloudPakForDataAuthenticator } = require('ibm-watson/auth');

const speechToText = new SpeechToTextV1({
  authenticator: new CloudPakForDataAuthenticator({
    username: '{username}',
    password: '{password}',
    url: 'https://{cpd_cluster_host}',
  }),
  serviceUrl: '{url}',
  disableSslVerification: true,
});

Example to disable SSL verification with an installed service

from ibm_watson import SpeechToTextV1
from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator

authenticator = CloudPakForDataAuthenticator(
    '{username}',
    '{password}'
)

speech_to_text = SpeechToTextV1(
    authenticator=authenticator
)

speech_to_text.set_service_url('{url}')

speech_to_text.set_disable_ssl_verification(True)

Authentication

IBM Cloud services use IBM Cloud Identity and Access Management (IAM) to authenticate. With IBM Cloud Pak for Data, you pass a bearer token.

For IBM Cloud instances, you authenticate to the API by using IBM Cloud Identity and Access Management (IAM).

You can pass either a bearer token in an authorization header or an API key. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. For more information, see Authenticating to Watson services.

For testing and development, you can pass an API key directly.
For production use, unless you use the Watson SDKs, use an IAM token.

If you pass in an API key, use apikey for the username and the value of the API key as the password. For example, if the API key is f5sAznhrKQyvBFFaZbtF60m5tzLbqWhyALQawBg5TjRI in the service credentials, include the credentials in your call like this:

curl -u "apikey:f5sAznhrKQyvBFFaZbtF60m5tzLbqWhyALQawBg5TjRI"

For IBM Cloud instances, the SDK provides initialization methods for each form of authentication.

Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
Use the access token to manage the lifecycle yourself. You must periodically refresh the token.

For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.

IBM Cloud. Replace {apikey} and {url} with your service credentials.

curl -X {request_method} -u "apikey:{apikey}" "{url}/v1/{method}"

IBM Cloud. SDK managing the IAM token. Replace {apikey} and {url}.

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
SpeechToText speechToText = new SpeechToText(authenticator);
speechToText.setServiceUrl("{url}");

IBM Cloud. SDK managing the IAM token. Replace {apikey} and {url}.

const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const speechToText = new SpeechToTextV1({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

IBM Cloud. SDK managing the IAM token. Replace {apikey} and {url}.

from ibm_watson import SpeechToTextV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
speech_to_text = SpeechToTextV1(
    authenticator=authenticator
)

speech_to_text.set_service_url('{url}')

Cloud Pak for Data

For Cloud Pak for Data, you pass a bearer token in an Authorization header to authenticate to the API. The token is associated with a username.

For testing and development, you can use the bearer token that's displayed in the Cloud Pak for Data web client. To find this token, view the details for the service instance by clicking the name of the service in your list of instances. The details also include the service endpoint URL. Don't use this token in production because it does not expire.
For production use, create a user in the Cloud Pak for Data web client to use for authentication. Generate a token from that user's credentials with the POST /v1/authorize method.

For more information, see the Get authorization token method of the Cloud Pak for Data API reference.

For Cloud Pak for Data instances, pass either username and password credentials or a bearer token that you generate to authenticate to the API. Username and password credentials use basic authentication. However, the SDK manages the lifecycle of the token. Tokens are temporary security credentials. If you pass a token, you maintain the token lifecycle.

For production use, create a user in the Cloud Pak for Data web client to use for authentication, and decide which authentication mechanism to use.

To have the SDK manage the lifecycle of the token, use the username and password for that new user in your calls.
To manage the lifecycle of the token yourself, generate a token from that user's credentials. Call the POST /v1/authorize method to generate the token, and then pass the token in an Authorization header in your calls. You can see an example of the method on the Curl tab.

For more information, see the Get authorization token method of the Cloud Pak for Data API reference.

Don't use the bearer token that's displayed in the web client for the instance except during testing and development because that token does not expire.

To find your value for {url}, view the details for the service instance by clicking the name of the service in your list of instances in the Cloud Pak for Data web client.

Cloud Pak for Data. Generating a bearer token.

Replace {cpd_cluster_host} and {port} with the details for the service instance. Replace {username} and {password} with your Cloud Pak for Data credentials.

curl -k -X POST \
-H "cache-control: no-cache" \
-H "Content-Type: application/json" \
-d "{\"username\":\"{username}\",\"password\":\"{password}\"}" \
"https://{cpd_cluster_host}/icp4d-api/v1/authorize"

The response includes a token property.

Authenticating to the API. Replace {token} with your details.

curl -H "Authorization: Bearer {token}" "{url}/v1/{method}"

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. For {url}, see Endpoint URLs.

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("https://{cpd_cluster_host}/icp4d-api/v1/authorize", "{username}", "{password}");
SpeechToText speechToText = new SpeechToText(authenticator);
speechToText.setServiceUrl("{url}");

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. For {url}, see Endpoint URLs.

const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');
const { CloudPakForDataAuthenticator } = require('ibm-watson/auth');

const speechToText = new SpeechToTextV1({
  authenticator: new CloudPakForDataAuthenticator({
    username: '{username}',
    password: '{password}',
    url: 'https://{cpd_cluster_host}/icp4d-api/v1/authorize',
  }),
  serviceUrl: '{url}',
});

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. For {url}, see Endpoint URLs.

from ibm_watson import SpeechToTextV1
from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator

authenticator = CloudPakForDataAuthenticator(
    '{username}',
    '{password}',
    'https://{cpd_cluster_host}/icp4d-api/v1/authorize'
)

speech_to_text = SpeechToTextV1(
    authenticator=authenticator
)

speech_to_text.set_service_url('{url}')

Access between services

Your application might use more than one Watson service. You can grant access between services and you can grant access to more than one service for your applications.

For IBM Cloud services, the method to grant access between Watson services varies depending on the type of API key. For more information, see IAM access.

To grant access between IBM Cloud services, create an authorization between the services. For more information, see Granting access between services.
To grant access to your services by applications without using user credentials, create a service ID, add an API key, and assign access policies. For more information, see Creating and working with service IDs.

When you give a user ID access to multiple services, use an endpoint URL that includes the service instance ID (for example, https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/6bbda3b3-d572-45e1-8c54-22d6ed9e52c2). You can find the instance ID in two places:

By clicking the service instance row in the Resource list. The instance ID is the GUID in the details pane.
By clicking the name of the service instance in the list and looking at the credentials URL.

If you don't see the instance ID in the URL, the credentials predate service IDs. Add new credentials from the Service credentials page and use those credentials.

Because the Cloud Pak for Data bearer token is associated with a username, you can use the token for all CPD Watson services that are associated with the username.

Error handling

Speech to Text uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.

ErrorResponse

| Name | Description | |----------------------------------|-------------------------------------| | error
string | Description of the problem. | | code
integer | HTTP response code. | | code_description
string | Response message. | | warnings
string | Warnings associated with the error. |

The Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an IllegalArgumentException.

| Exception | Description | |------------------------------|-----------------------------------------------| | IllegalArgumentException | An invalid argument was passed to the method. |

When the Java SDK receives an error response from the Speech to Text service, it generates an exception from the com.ibm.watson.developer_cloud.service.exception package. All service exceptions contain the following fields.

| Field | Description | |----------------|------------------------------------------| | statusCode | The HTTP response code that is returned. | | message | A message that describes the error. |

Example error handling

try {
  // Invoke a method
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
  // Handle Request Too Large (413) exception
} catch (ServiceResponseException e) {
  // Base class for all exceptions caused by error responses from the service
  System.out.println("Service returned status code "
    + e.getStatusCode() + ": " + e.getMessage());
}

When the Node SDK receives an error response from the Speech to Text service, it creates an Error object with information that describes the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table.

Error

| Field | Description | |-------------|------------------------------------------| | code | The HTTP response code that is returned. | | message | A message that describes the error. |

Example error handling

speechToText.method(params)
  .catch(err => {
    console.log('error:', err);
  });

The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the Speech to Text service, it generates an ApiException with the following fields.

| Field | Description | |-------------|---------------------------------------------------------| | code | The HTTP response code that is returned. | | message | A message that describes the error. | | info | A dictionary of additional information about the error. |

Example error handling

from ibm_watson import ApiException
try:
    # Invoke a method
except ApiException as ex:
    print "Method failed with status code " + str(ex.code) + ": " + ex.message

Data handling

Additional headers

Some Watson services accept special parameters in headers that are passed with the request.

You can pass request header parameters in all requests or in a single request to the service.

To pass a request header, use the --header (-H) option with a curl request.

Example header parameter in a request

curl -X {request_method} \
-H "Request-Header: {header_value}" \
"{url}/v1/{method}"

To pass header parameters with every request, use the setDefaultHeaders method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, use the addHeader method as a modifier on the request before you execute it.

Example header parameter in a request

ReturnType returnValue = speechToText.methodName(parameters)
  .addHeader("Custom-Header", "{header_value}")
  .execute();

To pass header parameters with every request, specify the headers parameter when you create the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, use the headers method as a modifier on the request before you execute it.

Example header parameter in a request

const parameters = {
  {parameters}
};

speechToText.methodName(
  parameters,
  headers: {
    'Custom-Header': '{header_value}'
  })
   .then(result => {
    console.log(response);
  })
  .catch(err => {
    console.log('error:', err);
  });

To pass header parameters with every request, specify the set_default_headers method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, include headers as a dict in the request.

Example header parameter in a request

response = speech_to_text.methodName(
    parameters,
    headers = {
        'Custom-Header': '{header_value}'
    })

Response details

The Speech to Text service might return information to the application in response headers.

To access all response headers that the service returns, include the --include (-i) option with a curl request. To see detailed response data for the request, including request headers, response headers, and extra debugging information, include the --verbose (-v) option with the request.

Example request to access response headers

curl -X {request_method} {authentication_method} \
--include \
"{url}/v1/{method}"

To access information in the response headers, use one of the request methods that returns details with the response: executeWithDetails(), enqueueWithDetails(), or rxWithDetails(). These methods return a Response<T> object, where T is the expected response model. Use the getResult() method to access the response object for the method, and use the getHeaders() method to access information in response headers.

Example request to access response headers

Response<ReturnType> response = speechToText.methodName(parameters)
  .executeWithDetails();
// Access response from methodName
ReturnType returnValue = response.getResult();
// Access information in response headers
Headers responseHeaders = response.getHeaders();

All response data is available in the Response<T> object that is returned by each method. To access information in the response object, use the following properties.

Example request to access response headers

speechToText.methodName(parameters)
  .then(response => {
    console.log(response.headers);
  })
  .catch(err => {
    console.log('error:', err);
  });

| Property | Description | |-----------|-------------------------------------------------------| | result | Returns the response for the service-specific method. | | headers | Returns the response header information. | | status | Returns the HTTP status code. |

The return value from all service methods is a DetailedResponse object. To access information in the result object or response headers, use the following methods.

Example request to access response headers

speech_to_text.set_detailed_response(True)
response = speech_to_text.methodName(parameters)
## Access response from methodName
print(json.dumps(response.get_result(), indent=2))
## Access information in response headers
print(response.get_headers())
## Access HTTP response status
print(response.get_status_code())

DetailedResponse

| Method | Description | |---------------------|-------------------------------------------------------| | get_result() | Returns the response for the service-specific method. | | get_headers() | Returns the response header information. | | get_status_code() | Returns the HTTP status code. |

DetailedResponse

| Property | Description | |-----------|-------------------------------------------------------| | result | Returns the response for the service-specific method. | | headers | Returns the response header information. | | status | Returns the HTTP status code. |

DetailedResponse

| Property | Description | |--------------|----------------------------------------------------------------| | Result | Returns the result for the service-specific method. | | Response | Returns the raw JSON response for the service-specific method. | | Headers | Returns the response header information. | | StatusCode | Returns the HTTP status code. |

Data labels (IBM Cloud)

You can remove data associated with a specific customer if you label the data with a customer ID when you send a request to the service.

Use the X-Watson-Metadata header to associate a customer ID with the data. By adding a customer ID to a request, you indicate that it contains data that belongs to that customer.

Specify a random or generic string for the customer ID. Do not include personal data, such as an email address. Pass the string customer_id={id} as the argument of the header.

Labeling data is used only by methods that accept customer data.
Use the Delete labeled data method to remove data that is associated with a customer ID.

Use this process of labeling and deleting data only when you want to remove the data that is associated with a single customer, not when you want to remove data for multiple customers. For more information about Speech to Text and labeling data, see Information security.

For more information about how to pass headers, see Additional headers.

Data collection (IBM Cloud)

Example request with a service managed on IBM Cloud

curl -u "apikey:{apikey}" \
-H "X-Watson-Learning-Opt-Out: true" \
"{url}/{method}"

Example request with a service managed on IBM Cloud

Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Watson-Learning-Opt-Out", "true");

speechToText.setDefaultHeaders(headers);

Example request with a service managed on IBM Cloud

const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const speechToText = new SpeechToTextV1({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
  headers: {
    'X-Watson-Learning-Opt-Out': 'true'
  }
});

Example request with a service managed on IBM Cloud

speech_to_text.set_default_headers({'x-watson-learning-opt-out': "true"})

By default, Speech to Text service instances managed on IBM Cloud that are not part of Premium plans collect data about API requests and their results. This data is collected only to improve the services for future users. The collected data is not shared or made public. Data is not collected for services that are part of Premium plans.

To prevent IBM usage of your data for an API request, set the X-Watson-Learning-Opt-Out header parameter to true. You can also disable request logging at the account level. For more information, see Controlling request logging for Watson services.

You must set the header on each request that you do not want IBM to access for general service improvements.

You can set the header by using the setDefaultHeaders method of the service object.

You can set the header by using the headers parameter when you create the service object.

You can set the header by using the set_default_headers method of the service object.

Synchronous and asynchronous requests

The Java SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of service methods. All service methods implement the ServiceCall interface.

To call a method synchronously, use the execute method of the ServiceCall interface. You can call the execute method directly from an instance of the service.
To call a method asynchronously, use the enqueue method of the ServiceCall interface to receive a callback when the response arrives. The ServiceCallback interface of the method's argument provides onResponse and onFailure methods that you override to handle the callback.

Example synchronous request

ReturnType returnValue = speechToText.method(parameters).execute();

Example asynchronous request

speechToText.method(parameters).enqueue(new ServiceCallback<ReturnType>() {
  @Override public void onResponse(ReturnType response) {
    . . .
  }
  @Override public void onFailure(Exception e) {
    . . .
  }
});

Related information

Speech to Text docs
Release notes for IBM Cloud
Release notes for IBM Cloud Pak for Data
Javadoc for SpeechToText
Javadoc for sdk-core

WebSockets

Sends audio and returns transcription results for recognition requests over a WebSocket connection. Requests and responses are enabled over a single TCP connection that abstracts much of the complexity of the request to offer efficient implementation, low latency, high throughput, and an asynchronous response.

The endpoint for the WebSocket API is

wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}/v1/recognize

{location} indicates where your application is hosted:
- us-south for Dallas
- us-east for Washington, DC
- eu-de for Frankfurt
- au-syd for Sydney
- jp-tok for Tokyo
- eu-gb for London
- kr-seo for Seoul
{instance_id} indicates the unique identifier of the service instance. For more information about how to find the instance ID, see Access between services.

The examples in the documentation abbreviate wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id} to {ws_url}. So all WebSocket examples call the method as {ws_url}/v1/recognize.

You can pass a maximum of 100 MB and a minimum of 100 bytes of audio per recognition request. You can send multiple requests over a single WebSocket connection. The service automatically detects the endianness of the incoming audio and, for audio that includes multiple channels, downmixes the audio to one-channel mono during transcoding.

By default, the service returns only final results for any request. You can request interim results to see intermediate hypotheses as the transcription progress.

See also:

The WebSocket interface cannot be called from curl. Use a client-side scripting language to call the interface. The example request uses JavaScript to invoke the WebSocket recognize method.

The createRecognizeStream method is deprecated. Use the equivalent recognizeUsingWebSocket method instead.

The recognize_with_websocket method is deprecated. Use the equivalent recognize_using_websocket method instead.

Audio formats (content types)

The service accepts audio in the following formats (MIME types).

For formats that are labeled Required, you must use the content-type contentType content_type parameter with the request to specify the format of the audio.
For all other formats, you can omit the content-type contentType content_type parameter or specify application/octet-stream with the parameter to have the service automatically detect the format of the audio.

Where indicated, the format that you specify must include the sampling rate and can optionally include the number of channels and the endianness of the audio.

application/octet-stream
audio/alaw (Required. Specify the sampling rate (rate) of the audio.)
audio/basic (Required. Use only with narrowband models.)
audio/flac
audio/g729 (Use only with narrowband models.)
audio/l16 (Required. Specify the sampling rate (rate) and optionally the number of channels (channels) and endianness (endianness) of the audio.)
audio/mp3
audio/mpeg
audio/mulaw (Required. Specify the sampling rate (rate) of the audio.)
audio/ogg (The service automatically detects the codec of the input audio.)
audio/ogg;codecs=opus
audio/ogg;codecs=vorbis
audio/wav (Provide audio with a maximum of nine channels.)
audio/webm (The service automatically detects the codec of the input audio.)
audio/webm;codecs=opus
audio/webm;codecs=vorbis

See also:

Supported audio formats

The Python recognize_using_websocket method requires the content_type parameter.

Large speech models and Next-generation models

The service supports large speech models and next-generation Multimedia (16 kHz) and Telephony (8 kHz) models for many languages. Large speech models and next-generation models have higher throughput than the service's previous generation of Broadband and Narrowband models. When you use large speech models and next-generation models, the service can return transcriptions more quickly and also provide noticeably better transcription accuracy.

You specify a large speech model or next-generation model by using the model parameter, as you do a previous-generation model. Only the next-generation models support the low_latency parameter, and all large speech models and next-generation models support the character_insertion_bias parameter. These parameters are not available with previous-generation models.

Large speech models and next-generation models do not support all of the speech recognition parameters that are available for use with previous-generation models. Next-generation models do not support the following parameters:

acoustic_customization_id
keywords and keywords_threshold
processing_metrics and processing_metrics_interval
word_alternatives_threshold

Effective 31 July 2023, all previous-generation models will be removed from the service and the documentation. Most previous-generation models were deprecated on 15 March 2022. You must migrate to the equivalent large speech model or next-generation model by 31 July 2023. For more information, see Migrating to large speech models.

See also:

URI /v1/recognize

okhttp3.WebSocket recognizeUsingWebSocket(RecognizeOptions options,
  RecognizeCallback callback)

RecognizeStream recognizeUsingWebSocket(params)

dict recognize_using_websocket(audio, content_type,
  recognize_callback, model=None,
  language_customization_id=None, acoustic_customization_id=None,
  customization_weight=None, base_model_version=None,
  inactivity_timeout=None, interim_results=None,
  keywords=None, keywords_threshold=None,
  max_alternatives=None, word_alternatives_threshold=None,
  word_confidence=None, timestamps=None, profanity_filter=None,
  smart_formatting=None, speaker_labels=None, http_proxy_host=None,
  http_proxy_port=None, customization_id=None, grammar_name=None,
  redaction=None, processing_metrics=None, processing_metrics_interval=None,
  audio_metrics=None, end_of_phrase_silence_time=None,
  split_transcript_at_phrase_end=None, speech_detector_sensitivity=None, sad_module=None, speech_begin_event=None, enrichments=None, background_audio_suppression=None, **kwargs)

Request

Example request

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/recognize'
  + '?access_token=' + access_token
  + '&model=en-US_BroadbandModel';

var websocket = new WebSocket(wsURI);
websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

function onOpen(evt) {
  var message = {
    action: 'start',
    keywords: ['colorado', 'tornado', 'tornadoes'],
    keywords_threshold: 0.5,
    max-alternatives: 3
  };
  websocket.send(JSON.stringify(message));

  // Prepare and send the audio file.
  websocket.send(blob);

  websocket.send(JSON.stringify({action: 'stop'}));
}

function onClose(evt) {
  console.log(evt.data);
}

function onMessage(evt) {
  console.log(evt.data);
}

function onError(evt) {
  console.log(evt.data);
}

Example request

/* * * * *
 * IBM CLOUD: Use the following code only to
 * authenticate to IBM Cloud.
 * * * * */

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
SpeechToText speechToText = new SpeechToText(authenticator);
speechToText.setServiceUrl("{url}");

/* * * * *
 * IBM CLOUD PAK FOR DATA: Use the following code
 * only to authenticate to IBM Cloud Pak for Data.
 * * * * */

// CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("https://{cpd_cluster_host}", "{username}", "{password}");
// SpeechToText speechToText = new SpeechToText(authenticator);
// speechToText.setServiceUrl("{url}");

try {
  RecognizeOptions recognizeOptions = new RecognizeOptions.Builder()
    .audio(new FileInputStream("audio-file.flac"))
    .contentType("audio/flac")
    .model("en-US_BroadbandModel")
    .keywords(Arrays.asList("colorado", "tornado", "tornadoes"))
    .keywordsThreshold((float) 0.5)
    .maxAlternatives(3)
    .build();

  BaseRecognizeCallback baseRecognizeCallback =
    new BaseRecognizeCallback() {

      @Override
      public void onTranscription
        (SpeechRecognitionResults speechRecognitionResults) {
          System.out.println(speechRecognitionResults);
      }

      @Override
      public void onDisconnected() {
        System.exit(0);
      }

    };

  speechToText.recognizeUsingWebSocket(recognizeOptions,
    baseRecognizeCallback);
} catch (FileNotFoundException e) {
  e.printStackTrace();
}

Example request

const fs = require('fs');
const SpeechToTextV1 = require('ibm-watson/speech-to-text/v1');

/* * * * *
 * IBM CLOUD: Use the following code only to
 * authenticate to IBM Cloud.
 * * * * */

const { IamAuthenticator } = require('ibm-watson/auth');
const speechToText = new SpeechToTextV1({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

/* * * * *
 * IBM CLOUD PAK FOR DATA: Use the following code
 * only to authenticate to IBM Cloud Pak for Data.
 * * * * */

// const { CloudPakForDataAuthenticator } = require('ibm-watson/auth');
// const speechToText = new SpeechToTextV1({
//   authenticator: new CloudPakForDataAuthenticator({
//     username: '{username}',
//     password: '{password}',
//     url: 'https://{cpd_cluster_host}',
//  }),
//  serviceUrl: '{url}',
// });

const params = {
  objectMode: true,
  contentType: 'audio/flac',
  model: 'en-US_BroadbandModel',
  keywords: ['colorado', 'tornado', 'tornadoes'],
  keywordsThreshold: 0.5,
  maxAlternatives: 3,
};

// Create the stream.
const recognizeStream = speechToText.recognizeUsingWebSocket(params);

// Pipe in the audio.
fs.createReadStream('audio-file.flac').pipe(recognizeStream);

/*
 * Uncomment the following two lines of code ONLY if `objectMode` is `false`.
 *
 * WHEN USED TOGETHER, the two lines pipe the final transcript to the named
 * file and produce it on the console.
 *
 * WHEN USED ALONE, the following line pipes just the final transcript to
 * the named file but produces numeric values rather than strings on the
 * console.
 */
// recognizeStream.pipe(fs.createWriteStream('transcription.txt'));

/*
 * WHEN USED ALONE, the following line produces just the final transcript
 * on the console.
 */
// recognizeStream.setEncoding('utf8');

// Listen for events.
recognizeStream.on('data', function(event) { onEvent('Data:', event); });
recognizeStream.on('error', function(event) { onEvent('Error:', event); });
recognizeStream.on('close', function(event) { onEvent('Close:', event); });

// Display events on the console.
function onEvent(name, event) {
    console.log(name, JSON.stringify(event, null, 2));
};

Example request

import json
from os.path import join, dirname
from ibm_watson import SpeechToTextV1
from ibm_watson.websocket import RecognizeCallback, AudioSource

##########
## IBM CLOUD: Use the following code only to
## authenticate to IBM Cloud.
##########

from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
authenticator = IAMAuthenticator('{apikey}')
speech_to_text = SpeechToTextV1(
    authenticator=authenticator
)
speech_to_text.set_service_url('{url}')

##########
## IBM CLOUD PAK FOR DATA: Use the following code
## only to authenticate to IBM Cloud Pak for Data.
##########

## from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator
## authenticator = CloudPakForDataAuthenticator(
## '{username}',
## '{password}',
## 'https://{cpd_cluster_host}'
## )
## speech_to_text = SpeechToTextV1(
## authenticator=authenticator
## )
## speech_to_text.set_service_url('{url}')

class MyRecognizeCallback(RecognizeCallback):
    def __init__(self):
        RecognizeCallback.__init__(self)

    def on_data(self, data):
        print(json.dumps(data, indent=2))

    def on_error(self, error):
        print('Error received: {}'.format(error))

    def on_inactivity_timeout(self, error):
        print('Inactivity timeout: {}'.format(error))

myRecognizeCallback = MyRecognizeCallback()

with open(join(dirname(__file__), './.', 'audio-file.flac'),
              'rb') as audio_file:
    audio_source = AudioSource(audio_file)
    speech_to_text.recognize_using_websocket(
        audio=audio_source,
        content_type='audio/flac',
        recognize_callback=myRecognizeCallback,
        model='en-US_BroadbandModel',
        keywords=['colorado', 'tornado', 'tornadoes'],
        keywords_threshold=0.5,
        max_alternatives=3)

The client calls the recognize method to obtain a string that contains the URI for the WebSocket interface. The call to the recognize method sets basic parameters for the connection and for all recognition requests that are sent over it. See the Parameters of recognize method table.

The client then establishes a connection with the service by passing the URI to the WebSocket constructor, which returns a WebSocket connection object. The client initiates and manages recognition requests by sending JSON-formatted text messages to the service over the connection. The text messages can include all other parameters of the recognition request. The required action parameter tells the service which action is to be performed. See the Parameters of WebSocket text messages table.

After sending the text message to initiate a request, the client sends the audio data to be transcribed as a binary message (blob) over the connection.

Parameters of recognize method

access_token

Required*
string
Pass a valid access token to establish an authenticated connection with the service. You must establish the connection before the access token expires. You pass an access token only to establish an authenticated connection. After you establish a connection, you can keep it alive indefinitely. You remain authenticated for as long as you keep the connection open. You do not need to refresh the access token for an active connection that lasts beyond the token's expiration time. After a connection is established, it can remain active even after the token or its credentials are deleted.
- IBM Cloud only. Pass an Identity and Access Management (IAM) access token to authenticate with the service. You pass an IAM access token instead of passing an API key with the call. For more information, see Authenticating to IBM Cloud.
- IBM Cloud Pak for Data only. Pass an access token as you would with the Authorization header of an HTTP request. For more information, see Authenticating to IBM Cloud Pak for Data.
model
string

The model to use for all speech recognition requests that are sent over the connection. See Using a model for speech recognition.

The default model is en-US_BroadbandModel. For Speech to Text for IBM Cloud Pak for Data, if you do not install the en-US_BroadbandModel, you must either specify a model with the request or specify a new default model for your installation of the service. For more information, see Using the default model.

Allowable values: [ar-MS_BroadbandModel, ar-MS_Telephony, cs-CZ_Telephony, de-DE, de-DE_BroadbandModel, de-DE_Multimedia, de-DE_NarrowbandModel, de-DE_Telephony, en-AU, en-AU_BroadbandModel, en-AU_Multimedia, en-AU_NarrowbandModel, en-AU_Telephony, en-GB, en-GB_BroadbandModel, en-GB_Multimedia, en-GB_NarrowbandModel, en-GB_Telephony, en-IN, en-IN_Telephony, en-US, en-US_BroadbandModel, en-US_Multimedia, en-US_NarrowbandModel, en-US_ShortForm_NarrowbandModel, en-US_Telephony, en-WW_Medical_Telephony, es-AR, es-AR_BroadbandModel, es-AR_NarrowbandModel, es-CL, es-CL_BroadbandModel, es-CL_NarrowbandModel, es-CO, es-CO_BroadbandModel, es-CO_NarrowbandModel, es-ES, es-ES_BroadbandModel, es-ES_NarrowbandModel, es-ES_Multimedia, es-ES_Telephony, es-LA_Telephony, es-MX, es-MX_BroadbandModel, es-MX_NarrowbandModel, es-PE, es-PE_BroadbandModel, es-PE_NarrowbandModel, fr-CA, fr-CA_BroadbandModel, fr-CA_Multimedia, fr-CA_NarrowbandModel, fr-CA_Telephony, fr-FR, fr-FR_BroadbandModel, fr-FR_Multimedia, fr-FR_NarrowbandModel, fr-FR_Telephony, hi-IN_Telephony, it-IT_BroadbandModel, it-IT_NarrowbandModel, it-IT_Multimedia, it-IT_Telephony, ja-JP, ja-JP_BroadbandModel, ja-JP_Multimedia, ja-JP_NarrowbandModel, ja-JP_Telephony, ko-KR_BroadbandModel, ko-KR_Multimedia, ko-KR_NarrowbandModel, ko-KR_Telephony, nl-BE_Telephony, nl-NL_BroadbandModel, nl-NL_Multimedia, nl-NL_NarrowbandModel, nl-NL_Telephony, pt-BR, pt-BR_BroadbandModel, pt-BR_Multimedia, pt-BR_NarrowbandModel, pt-BR_Telephony, sv-SE_Telephony, zh-CN_BroadbandModel, zh-CN_NarrowbandModel, zh-CN_Telephony]

Default: en-US_BroadbandModel
language_customization_id
string

The customization ID (GUID) of a custom language model that is to be used for all requests sent over the connection. The base model of the specified custom language model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom language model. See Using a custom language model for speech recognition.
acoustic_customization_id
string

The customization ID (GUID) of a custom acoustic model that is to be used for the request. The base model of the specified custom acoustic model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom acoustic model. See Using a custom acoustic model for speech recognition.
base_model_version
string

The version of the specified base model that is to be used for all requests sent over the connection. Multiple versions of a base model can exist when a model is updated for internal improvements. The parameter is intended primarily for use with custom models that have been upgraded for a new base model. The default value depends on whether the parameter is used with or without a custom model. See Making speech recognition requests with upgraded custom models.
enrichments
string

Speech transcript enrichment improves readability of raw ASR transcripts by adding punctuation (periods, commas, question marks, exclamation points) and intelligent capitalization (sentence beginnings, proper nouns, acronyms, brand names). To enable enrichment, add the enrichments=punctuation parameter to your recognition request. Supported languages include English (US, UK, Australia, India), French (France, Canada), German, Italian, Portuguese (Brazil, Portugal), Spanish (Spain, Latin America, Argentina, Chile, Colombia, Mexico, Peru), and Japanese. See Speech transcript enrichment.
x-watson-learning-opt-out
string

Indicates whether IBM can use data that is sent over the connection to improve the service for future users. Specify true to prevent IBM from accessing the logged data. See Data collection.

Default: false
x-watson-metadata
string

Associates a customer ID with all data that is passed over the connection. The parameter accepts the argument customer_id={id}, where {id} is a random or generic string that is to be associated with the data. URL-encode the argument to the parameter, for example customer_id%3dmy_ID. By default, no customer ID is associated with the data. See Data labels.

Call the recognizeUsingWebSocket method to initiate a recognition request. Use the recognizeOptions argument to pass a RecognizeOptions object that provides the parameters for the request, including the audio. Use the callback argument to pass a Java BaseRecognizeCallback object to handle events from the WebSocket connection.

Call the recognizeUsingWebSocket method to initiate a recognition request. The method returns a RecognizeStream object to which you pipe the audio that is to be transcribed. You also use the object's on method to define event handlers for the request. You pass all other parameters of the request as arguments of the method.

Call the recognize_using_websocket method to initiate a recognition request. Pass the audio and all parameters of the request, including the RecognizeCallback and AudioSource objects, as arguments of the method.

Parameters of WebSocket text messages

Parameters

action

Required*
string
The action that is to be performed.

Allowable values:
- start initiates a recognition request. The message can also include any other optional parameters that are described in this table. After sending this text message, the client sends the data as a binary message (blob).
  
  Between recognition requests, the client can send new start messages to modify the parameters that are to be used for subsequent requests. By default, the service continues to use the parameters that were specified with the previous start message.
- stop indicates that all audio data for the request has been sent to the service. The client can send additional requests with the same or different parameters.
objectMode
boolean
Indicates how the data event handler is to return the response from the service:
- If false, the event handler returns only a string with the final transcription of the recognition results, regardless of the parameters that you pass with the request. You must set the encoding for your instance of the RecognizeStream object to UTF-8 by including a call that is similar to the following line of code in your application:
  
  recognizeStream.setEncoding('utf8');
  
  Do not include this call if you set the objectMode parameter to true.
- If true, the event handler returns the recognition results exactly as it receives them from the service: as one or more instances of a SpeechRecognitionResults object.
For more information, see the Example request for the method.
audio

Required*
java.io.InputStream AudioSource

The audio that is to be transcribed.

An AudioSource object that provides the audio that is to be transcribed.
content-type

contentType

content_type

Required*
string str

The format (MIME type) of the audio. For more information about specifying an audio format, see Audio formats (content types) in the method description.

Allowable values: [application/octet-stream, audio/alaw, audio/basic, audio/flac, audio/g729, 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]
callback

recognize_callback

Required*
object

A BaseRecognizeCallback object that implements the RecognizeCallback interface to handle events from the WebSocket connection. Override the definitions of the object's default methods to respond to events as needed by your application.

A RecognizeCallback object that defines methods to handle events from the WebSocket connection. Override the definitions of the object's default methods to respond to events as needed by your application.
model
string str

The model to use for all speech recognition requests that are sent over the connection. See Using a model for speech recognition.

The default model is en-US_BroadbandModel. For Speech to Text for IBM Cloud Pak for Data, if you do not install the en-US_BroadbandModel, you must either specify a model with the request or specify a new default model for your installation of the service. For more information, see Using the default model.

Allowable values: [ar-MS_BroadbandModel, ar-MS_Telephony, cs-CZ_Telephony, de-DE, de-DE_BroadbandModel, de-DE_Multimedia, de-DE_NarrowbandModel, de-DE_Telephony, en-AU, en-AU_BroadbandModel, en-AU_Multimedia, en-AU_NarrowbandModel, en-AU_Telephony, en-GB, en-GB_BroadbandModel, en-GB_Multimedia, en-GB_NarrowbandModel, en-GB_Telephony, en-IN, en-IN_Telephony, en-US, en-US_BroadbandModel, en-US_Multimedia, en-US_NarrowbandModel, en-US_ShortForm_NarrowbandModel, en-US_Telephony, en-WW_Medical_Telephony, es-AR, es-AR_BroadbandModel, es-AR_NarrowbandModel, es-CL, es-CL_BroadbandModel, es-CL_NarrowbandModel, es-CO, es-CO_BroadbandModel, es-CO_NarrowbandModel, es-ES, es-ES_BroadbandModel, es-ES_NarrowbandModel, es-ES_Multimedia, es-ES_Telephony, es-LA_Telephony, es-MX, es-MX_BroadbandModel, es-MX_NarrowbandModel, es-PE, es-PE_BroadbandModel, es-PE_NarrowbandModel, fr-CA, fr-CA_BroadbandModel, fr-CA_Multimedia, fr-CA_NarrowbandModel, fr-CA_Telephony, fr-FR, fr-FR_BroadbandModel, fr-FR_Multimedia, fr-FR_NarrowbandModel, fr-FR_Telephony, hi-IN_Telephony, it-IT_BroadbandModel, it-IT_NarrowbandModel, it-IT_Multimedia, it-IT_Telephony, ja-JP, ja-JP_BroadbandModel, ja-JP_Multimedia, ja-JP_NarrowbandModel, ja-JP_Telephony, ko-KR_BroadbandModel, ko-KR_Multimedia, ko-KR_NarrowbandModel, ko-KR_Telephony, nl-BE_Telephony, nl-NL_BroadbandModel, nl-NL_Multimedia, nl-NL_NarrowbandModel, nl-NL_Telephony, pt-BR, pt-BR_BroadbandModel, pt-BR_Multimedia, pt-BR_NarrowbandModel, pt-BR_Telephony, sv-SE_Telephony, zh-CN_BroadbandModel, zh-CN_NarrowbandModel, zh-CN_Telephony]

Default: en-US_BroadbandModel
speech_begin_event

speechBeginEvent
boolean bool

If true, the service returns a response object SpeechActivity which contains the time when a speech activity is detected in the stream. This can be used both in standard and low latency mode. This feature enables client applications to know that some words/speech has been detected and the service is in the process of decoding. This can be used in lieu of interim results in standard mode. Use sad_module: 2 to increase accuracy and performance in detecting speech boundaries within the audio stream. See Using speech recognition parameters.

Default: false
enrichments

enrichments
string str

Speech transcript enrichment improves readability of raw ASR transcripts by adding punctuation (periods, commas, question marks, exclamation points) and intelligent capitalization (sentence beginnings, proper nouns, acronyms, brand names). To enable enrichment, add the enrichments=punctuation parameter to your recognition request. Supported languages include English (US, UK, Australia, India), French (France, Canada), German, Italian, Portuguese (Brazil, Portugal), Spanish (Spain, Latin America, Argentina, Chile, Colombia, Mexico, Peru), and Japanese. See Speech transcript enrichment.
languageCustomizationId

language_customization_id
string str

The customization ID (GUID) of a custom language model that is to be used for the request. The base model of the specified custom language model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom language model. See Using a custom language model for speech recognition.
acousticCustomizationId

acoustic_customization_id
string str

The customization ID (GUID) of a custom acoustic model that is to be used for the request. The base model of the specified custom acoustic model must match the model that is specified with the model parameter. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified model with no custom acoustic model. See Using a custom acoustic model for speech recognition.
customization_weight

customizationWeight
double float
If you specify a customization ID when you open the connection, If you specify a customization ID, you can use the customization weight to tell the service how much weight to give to words from the custom language model compared to those from the base model for the current request.

Specify a value between 0.0 and 1.0. Unless a different customization weight was specified for the custom model when the model was trained, the default value is:
- 0.5 for large speech models
- 0.3 for previous-generation models
- 0.2 for most next-generation models
- 0.1 for next-generation English and Japanese models
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 you set the weight: a higher value can improve the accuracy of phrases from the custom model's domain, but it can negatively affect performance on non-domain phrases.

See Using customization weight.
base_model_version

baseModelVersion
string str

The version of the specified base model that is to be used for the request. Multiple versions of a base model can exist when a model is updated for internal improvements. The parameter is intended primarily for use with custom models that have been upgraded for a new base model. The default value depends on whether the parameter is used with or without a custom model. See Making speech recognition requests with upgraded custom models.
inactivity_timeout

inactivityTimeout
integer int

The time in seconds after which, if only silence (no speech) is detected in the audio, the connection is closed. The default is 30 seconds. The parameter is useful for stopping audio submission from a live microphone when a user simply walks away. Use -1 for infinity. See Inactivity timeout.

Default: 30
interim_results

interimResults
boolean bool
If true, the service returns intermediate hypotheses as a stream of JSON SpeechRecognitionResults objects before returning final results for an utterance. If false, the service returns only a single SpeechRecognitionResults object with final results for any utterance. (See the objectMode parameter for information about controlling the response from the method.)
- For previous-generation models, interim results are available for all models. To receive interim results, set the interim_results interimResults parameter to true.
- For next-generation models, interim results are available only for those models that support low latency. To receive interim results, see both the interim_results interimResults and low_latency lowLatency parameters to true.
For for information, see:
Default: false
keywords
string[] [string] list[str]

An array of keyword strings to spot in the audio. Each keyword string can include one or more string tokens. Keywords are spotted only in the final results, not in interim hypotheses. If you specify any keywords, you must also specify a keywords threshold. Omit the parameter or specify an empty array if you do not need to spot keywords.

You can spot a maximum of 1000 keywords with a single request. A single keyword can have a maximum length of 1024 characters, though the maximum effective length for double-byte languages might be shorter. Keywords are case-insensitive.

See Keyword spotting.
keywords_threshold

keywordsThreshold
float

A confidence value that is the lower bound for spotting a keyword. A word is considered to match a keyword if its confidence is greater than or equal to the threshold. Specify a probability between 0.0 and 1.0. No keyword spotting is performed if you omit the parameter. If you specify a threshold, you must also specify one or more keywords. See Keyword spotting.
max_alternatives

maxAlternatives
integer int

The maximum number of alternative transcripts that the service is to return. By default, the service returns a single transcript. If you specify a value of 0, the service uses the default value, 1. See Maximum alternatives.

Default: 1
word_alternatives_threshold

wordAlternativesThreshold
float

A confidence value that is the lower bound for identifying a hypothesis as a possible word alternative (also known as "Confusion Networks"). An alternative word is considered if its confidence is greater than or equal to the threshold. Specify a probability between 0.0 and 1.0. By default, the service computes no alternative words. See Word alternatives.
word_confidence

wordConfidence
boolean bool

If true, the service returns a confidence measure in the range of 0.0 to 1.0 for each word. By default, no word confidence measures are returned. See Word confidence.

Default: false
timestamps
boolean bool

If true, the service returns time alignment for each word. By default, no timestamps are returned. See Word timestamps.

Default: false
profanity_filter

profanityFilter
boolean bool

If true, the service filters profanity from all output except for keyword results by replacing inappropriate words with a series of asterisks. Set the parameter to false to return results with no censoring.

Note: The parameter can be used with US English and Japanese transcription only. See Profanity filtering.

Default: true
smart_formatting

smartFormatting
boolean bool

If true, the service converts dates, times, series of digits and numbers, phone numbers, currency values, and internet addresses into more readable, conventional representations in the final transcript of a recognition request. For US English, the service also converts certain keyword strings to punctuation symbols. By default, no smart formatting is performed.

Beta: The parameter is beta functionality. It can be used with US English, Japanese, and Spanish (all dialects) transcription only. See Smart formatting.

Default: false
smart_formatting_version

smartFormattingVersion
integer int

Smart formatting version for large speech models and next-generation models is supported in US English, Brazilian Portuguese, French, German, Spanish and French Canadian languages.

See Smart formatting Version.

Default: 0
speaker_labels

speakerLabels
boolean bool
If true, the response includes labels that identify which words were spoken by which participants in a multi-person exchange. By default, the service returns no speaker labels. Setting speaker_labels speakerLabels to true forces the timestamps parameter to be true, regardless of whether you specify false for the parameter.
- For previous-generation models, can be used with Australian English, US English, German, Japanese, Korean, and Spanish (both broadband and narrowband models) and UK English (narrowband model) transcription only.
- For large speech models and next-generation models, can be used with all available languages.
See Speaker labels.

Default: false
http_proxy_host
str

If you are passing requests through a proxy, specify the hostname of the proxy server. Use the http_proxy_port parameter to specify the port number at which the proxy listens. Omit both parameters if you are not using a proxy.

Default: None
http_proxy_port
str

If you are passing requests through a proxy, specify the port number at which the proxy service listens. Use the http_proxy_host parameter to specify the hostname of the proxy. Omit both parameters if you are not using a proxy.

Default: None
grammarName

grammar_name
string str

The name of a grammar that is to be used with the recognition request. If you specify a grammar, you must also use the language_customization_id languageCustomizationId parameter to specify the name of the custom language model for which the grammar is defined. The service recognizes only strings that are recognized by the specified grammar; it does not recognize other custom words from the model's words resource.
redaction
boolean bool

If true, the service redacts, or masks, numeric data from final transcripts. The feature redacts any number that has three or more consecutive digits by replacing each digit with an X character. It is intended to redact sensitive numeric data, such as credit card numbers. By default, the service performs no redaction.

When you enable redaction, the service automatically enables smart formatting, regardless of whether you explicitly disable that feature. To ensure maximum security, the service also disables keyword spotting (ignores the keywords and keywords_threshold keywordsThreshold parameters) and returns only a single final transcript (forces the max_alternatives maxAlternatives parameter to be 1).

Beta: The parameter is beta functionality. It can be used with US English, Japanese, and Korean transcription only. See Numeric redaction.

Default: false
processing_metrics

processingMetrics
boolean bool

If true, requests processing metrics about the service's transcription of the input audio. The service returns processing metrics at the interval that is specified by the processing_metrics_interval processingMetricsInterval parameter. It also returns processing metrics for transcription events, for example, for final and interim results. By default, the service returns no processing metrics. See Processing metrics.

Default: false
processing_metrics_interval

processingMetricsInterval
float

Specifies the interval in seconds at which the service is to return processing metrics. The parameter is ignored unless the processing_metrics processingMetrics parameter is set to true.

The parameter accepts a minimum value of 0.1 seconds. The level of precision is not restricted, so you can specify values such as 0.25 and 0.125.

The service does not impose a maximum value. If you want to receive processing metrics only for transcription events instead of at periodic intervals, set the value to a large number. If the value is larger than the duration of the audio, the service returns processing metrics only for transcription events.

See Processing metrics.

Default: 1.0
audio_metrics

audioMetrics
boolean bool

If true, requests detailed information about the signal characteristics of the input audio. The service returns audio metrics with the final transcription results. By default, the service returns no audio metrics. See Audio metrics.

Default: false
end_of_phrase_silence_time

endOfPhraseSilenceTime
double float
Specifies the duration of the pause interval at which the service splits a transcript into multiple final results. If the service detects pauses or extended silence before it reaches the end of the audio stream, its response can include multiple final results. Silence indicates a point at which the speaker pauses between spoken words or phrases.

Specify a value for the pause interval in the range of 0.0 to 120.0.
- A value greater than 0 specifies the interval that the service is to use for speech recognition.
- A value of 0 indicates that the service is to use the default interval. It is equivalent to omitting the parameter.
The default pause interval for most languages is 0.8 seconds. The default for Chinese is 0.6 seconds.

See End of phrase silence time.

Default: 0.8
split_transcript_at_phrase_end

splitTranscriptAtPhraseEnd
boolean bool

If true, directs the service to split the transcript into multiple final results based on semantic features of the input, for example, at the conclusion of meaningful phrases such as sentences. The service bases its understanding of semantic features on the base language model that you use with a request. Custom language models and grammars can also influence how and where the service splits a transcript.

By default, the service splits transcripts based solely on the pause interval. If the parameters are used together on the same request, end_of_phrase_silence_time has precedence over split_transcript_at_phrase_end.

See Split transcript at phrase end.

Default: false
speech_detector_sensitivity

speechDetectorSensitivity
double float
The sensitivity of speech activity detection that the service is to perform. Use the parameter to suppress word insertions from music, coughing, and other non-speech events. The service biases the audio it passes for speech recognition by evaluating the input audio against prior models of speech and non-speech activity.

Specify a value between 0.0 and 1.0:
- 0.0 suppresses all audio (no speech is transcribed).
- 0.5 (the default) provides a reasonable compromise for the level of sensitivity.
- 1.0 suppresses no audio (speech detection sensitivity is disabled).
The values increase on a monotonic curve. Specifying one or two decimal places of precision (for example, 0.55) is typically more than sufficient.

The parameter is supported with all large speech models, next-generation models and with most previous-generation models. See Speech detector sensitivity and Language model support.

Default: 0.5
sad_module

speechActivityDetection
integer int

Detects speech boundaries within the audio stream with better performance, improved noise suppression, faster responsiveness, and increased accuracy.

Specify sad_module: 2.

See Speech Activity Detection (SAD).

Default: sad_module: 1
background_audio_suppression

backgroundAudioSuppression
double float
The level to which the service is to suppress background audio based on its volume to prevent it from being transcribed as speech. Use the parameter to suppress side conversations or background noise.

Specify a value between 0.0 and 1.0:
- 0.0 (the default) provides no suppression (background audio suppression is disabled).
- 0.5 provides a reasonable level of audio suppression for general usage.
- 1.0 suppresses all audio (no audio is transcribed).
The values increase on a monotonic curve. Specifying one or two decimal places of precision (for example, 0.55) is typically more than sufficient.

The parameter is supported with all large speech models, next-generation models and with most previous-generation models. See Background audio suppression and Language model support.

Default: 0.0
low_latency

lowLatency
boolean bool
If true for next-generation Multimedia and Telephony models that support low latency, directs the service to produce results even more quickly than it usually does. Next-generation models produce transcription results faster than previous-generation models. The low_latency parameter causes the models to produce results even more quickly, though the results might be less accurate when the parameter is used.

Note: The low_latency lowLatency parameter is not available for large speech models and previous-generation Broadband and Narrowband models. It is available only for some next-generation models. To obtain interim results with a next-generation model, the model must support low latency and both the interim_results interimResults and low_latency lowLatency parameters must be set to true.
- For a list of next-generation models that support low latency, see Supported next-generation language models.
- For more information about the low_latency lowLatency parameter, see Low latency.
Default: false
character_insertion_bias
float
For large speech models and next-generation models, an indication of whether the service is biased to recognize shorter or longer strings of characters when developing transcription hypotheses. By default, the service is optimized to produce the best balance of strings of different lengths.

The default bias is 0.0. The allowable range of values is -1.0 to 1.0.
- Negative values bias the service to favor hypotheses with shorter strings of characters.
- Positive values bias the service to favor hypotheses with longer strings of characters.
As the value approaches -1.0 or 1.0, the impact of the parameter becomes more pronounced. To determine the most effective value for your scenario, start by setting the value of the parameter to a small increment, such as -0.1, -0.05, 0.05, or 0.1, and assess how the value impacts the transcription results. Then experiment with different values as necessary, adjusting the value by small increments.

Beta: The parameter is beta functionality. It is not available for previous-generation models.

See Character insertion bias.",

Response

Example response

{
  "results": [
    {
      "final": true,
      "alternatives": [
        {
          "transcript": "several tornadoes touch down as a line of severe thunderstorms swept through Colorado on Sunday ",
          "confidence": 0.89
        },
        {
          "transcript": "several tornadoes touch down is a line of severe thunderstorms swept through Colorado on Sunday "
        },
        {
          "transcript": "several tornadoes touched down as a line of severe thunderstorms swept through Colorado on Sunday "
        }
      ],
      "keywords_result": {
        "tornadoes": [
          {
            "normalized_text": "tornadoes",
            "start_time": 1.52,
            "end_time": 2.15,
            "confidence": 1.0
          }
        ],
        "colorado": [
          {
            "normalized_text": "Colorado",
            "start_time": 4.95,
            "end_time": 5.59,
            "confidence": 0.98
          }
        ]
      }
    }
  ],
  "result_index": 0
}

Successful recognition returns one or more instances of a SpeechRecognitionResults object. The contents of the response depend on the parameters you send with the recognition request, including the interim_results interimResults parameter. For more information, see the results for the Recognize audio method.

If the objectMode parameter is true, successful recognition returns one or more instances of a SpeechRecognitionResults object. The contents of the response depend on the parameters you send with the recognition request, including the interimResults parameter. For more information, see the results for the Recognize audio method.

If the objectMode parameter is false, successful recognition returns only a single string with the final transcription results.

Response handling

Response handling for the WebSocket interface is different from HTTP response handling. The WebSocket constructor returns an instance of a WebSocket connection object. You assign application-specific calls to the following methods of the object to handle events that are associated with the connection. Each event handler must accept a single argument for an event from the connection. The event that it accepts causes it to execute.

Methods

onopen({event})

The status of the connection's opening.
onmessage({event})

Response messages from the service, including the results of the request as one or more JSON SpeechRecognitionResults objects.
onerror({event})

Errors for the connection or request.
onclose({event})

The status of the connection's closing.

The callback parameter of the recognizeUsingWebSocket method accepts a Java object of type BaseRecognizeCallback, which implements the RecognizeCallback interface to handle events from the WebSocket connection. You override the definitions of the following default empty methods of the object to handle events that are associated with the connection and the request. The methods are called when their associated events occur.

Methods

void onConnected()

The WebSocket connection is established.
void onListening()

The service is listening for audio.
void onTranscription (SpeechRecognitionResults {speechRecognitionResults})

Results for the request are received from the service.
void onTranscriptionComplete()

Final results for the request have been returned by the service.
void onError(java.lang.Exception {e})

An error occurs in the WebSocket connection.
void onInactivityTimeout (java.lang.RuntimeException {runtimeException})

An inactivity timeout occurs for the request.
void onDisconnected()

The WebSocket connection is closed.

You handle events that are associated with the WebSocket connection and the request by defining event-handler methods on the RecognizeCallback object that is returned by the recognizeUsingWebSocket method. The methods are called when their associated events occur. You can define handlers for the following events by using the object's on method. For more information about streams and events, see the Node.js documentation.

Events

data

Results for the request are received on the stream.
readable

Data is available to be read from the stream.
end

No data remains to be read from the stream.
close

The WebSocket connection is closed.
error

An error occurs in the WebSocket connection.

The recognize_callback parameter of the recognize_using_websocket method accepts an object of type RecognizeCallback. The object defines the methods that handle events from the WebSocket connection. You can override the definitions of the following default empty methods of the object to handle events that are associated with the connection and the request. The methods are called when their associated events occur.

Methods

on_connected()

The WebSocket connection is established.
on_listening()

The service is listening for audio.
on_data({data})

Returns all response data for the request from the service.
on_hypothesis({hypothesis})

Returns interim results or maximum alternatives from the service when those responses are requested.
on_transcription({transcript})

Returns final transcription results for the request from the service.
on_error({error})

Reports an error in the WebSocket connection.
on_inactivity_timeout({error})

Reports an inactivity timeout for the request.

The connection can produce the following return codes.

Return code

1000

The connection closed normally.
1001

The connection closed because the remote peer is leaving.
1002

The connection closed due to a protocol error.
1003

The connection closed because the service could not process the input from the client.
1004

Reserved response code.
1005

The connection closed for a reason other than those defined by the remaining return codes.
1006

The connection closed abnormally.
1007

The connection closed because the service received invalid data.
1008

The connection closed due to a policy violation.
1009

The connection closed because the frame size exceeded the 4 MB limit.
1010

The connection closed because the client requested a required extension that is not available.
1011

The connection closed because the service encountered an unexpected internal condition that prevents it from fulfilling the request.
1015

The connection was not established due to a TLS handshake error.

Speech to Text | IBM Cloud API Docs