Creating a Watson Speech services instance

After you install the Speech services, you must create (provision) an instance of a service to begin using it. You can create an instance of a Speech service with the web client, with the API, or with the command-line interface. You can then send requests to verify that your service and instance are functioning properly.

  • You can install Speech to Text, Text to Speech, or both services in the same deployment namespace.
  • You can create multiple instances of either service that you install. If you install both services, you can create multiple instances of both services.
  • Individual instances of a Speech service are independent of each other. But all instances that are hosted in the same deployment share a common pool of hardware and software resources. For example, their stateful data is stored in the same set of datastores. This setup is known as a multi-tenant environment.
  • You can create an unlimited number of instances of either service. But you need to scale your installation to handle the number of concurrent connections that you expect the instances to handle. For more information, see Scaling up your Watson Speech services installation.
Important: The curl commands that are used in many of the examples return an authorization error if you use a self-signed certificate. To disable SSL (or TLS) verification for a request, include the --insecure (-k) option with the command. Disable SSL only if necessary for the simple verification requests and where indicated for requests to create a service instance. For more information about using curl, see Using curl with Watson examples.

Creating an instance topics

For more information about creating and validating a service instance, see the following topics:

For more information about granting users access to your service instances, and about listing and deleting instances, see Managing your Watson Speech services instances.

Creating a service instance with the web client

Permissions you need for this task

To create an instance with the web client, you must be an administrator of the Red Hat® OpenShift® project to manage the cluster.

Procedure

To create an instance of a Speech service by using the web client, complete the following steps:

  1. From the IBM Cloud Pak® for Data web client menu, click Services > Instances.
  2. From the instances page, click New instance.
  3. From the service's catalog page, select the service for which you want to create an instance, Watson Speech to Text or Watson Text to Speech.
  4. From the catalog page for the service, click New instance.
  5. From the Create service instance page, complete the following fields: Instance name, Description (optional), and Deployment. Then, click Create.
  6. Wait a few seconds for the new instance to be provisioned, and then reload the page.
  7. When the new service instance is created, the web client displays information about the instance on the About this instance page. Under Access information, the page includes the instance's URL (which includes its service instance ID) and the bearer token that you need to authorize requests to the instance.
    Example image that shows detailed information for a new Speech to Text instance.

Creating a service instance with the API

Permissions you need for this task

To create an instance with the API, you must have the can_provision permission in Cloud Pak for Data.

Prerequisite step

Before you can use the API, you must get an API key that you can use to obtain a token that you can pass with the requests. Follow the steps that are described in Authentication in IBM Cloud Pak for Data Platform API.

Procedure

To create an instance of a Speech service instance programmatically by using the API, complete the following steps:

  1. Get the hostname for the Cloud Pak for Data cluster where you want to create the service instance:
    oc get route cpd -n ${PROJECT_CPD_INSTANCE} -ojsonpath='{.spec.host}'

    You pass this hostname as the <host> variable in subsequent requests.

  2. Create a service instance:

    curl --insecure --request POST \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data "{\"addon_type\": \"speech-to-text\", \
    \"addon_version\": \"<version>\", \
    \"create_arguments\": { \
      \"deployment_id\": \"${PROJECT_CPD_INSTANCE}-${CUSTOM_RESOURCE_SPEECH}\", \
      \"parameters\" : { \
        \"serviceId\": \"speech-to-text\", \
        \"url\": \"https://${CUSTOM_RESOURCE_SPEECH}-gdpr-data-deletion.${PROJECT_CPD_INSTANCE}.svc.cluster.local:443\", \
        \"watson\": true \
      } \
    }, \
    \"display_name\": \"${CUSTOM_RESOURCE_SPEECH}-test-instance\", \
    \"namespace\": \"${PROJECT_CPD_INSTANCE}\" \
  }" \
 --url "https://<host>/zen-data/v3/service_instances"

    where

    <host>
    The hostname that you retrieved in the previous step.
    <token>
    The authorization token that you obtained when you completed the prerequisite step.
    addon_type
    One of speech-to-text or text-to-speech.
    <version>
    The version of the Cloud Pak for Data software that is installed, for example, 4.6.3.
    serviceId
    One of speech-to-text or text-to-speech.
    display_name
    The name that you want to use for the service instance. This name is displayed in the Instances page of the Cloud Pak for Data web client. The name can contain alphanumeric characters, spaces, dashes, underscores, and periods. In the example, the display_name is ${CUSTOM_RESOURCE_SPEECH}-test-instance.

    The response contains an id field that provides the ID of the service instance that is created. Make a note of the instance ID, which you need to issue requests to the service instance.

    {
  "id": "1670881541354464"
}

Creating a service instance with the CLI

Permissions you need for this task

To create an instance with the command-line interface (CLI), you must have the can_provision permission in Cloud Pak for Data.

Prerequisite steps

Before you can use the Cloud Pak for Data command-line interface (cpd-cli) to create a service instance, you must complete the following steps:

  1. Install the cpd-cli. For more information, see Installing the Cloud Pak for Data command-line interface (cpd-cli).
  2. Create a Cloud Pak for Data configuration profile name that has permission to provision instances. For more information, see Creating a profile to use the cpd-cli management commands.

Procedure

To create an instance of a Speech service instance by using the command-line interface (cpd-cli), complete the following steps.

  1. Create a JSON file that defines the service instance that you want to create. Store the file in a location from which it can be referenced when you submit a command to the cpd-cli in the next step.
    {
  "addon_type": "speech-to-text",
  "addon_version": "<version>",
  "create_arguments": {
    "deployment_id": "${PROJECT_CPD_INSTANCE}-${CUSTOM_RESOURCE_SPEECH}",
    "parameters" : {
      "serviceId": "speech-to-text",
      "url": "https://${CUSTOM_RESOURCE_SPEECH}-gdpr-data-deletion.${PROJECT_CPD_INSTANCE}.svc.cluster.local:443/v3/service_instances",
      "watson": true
    }
  },
  "display_name": "${CUSTOM_RESOURCE_SPEECH}-test-instance",
  "namespace": "${PROJECT_CPD_INSTANCE}"
}

    where

    addon_type
    One of speech-to-text or text-to-speech.
    <version>
    The version of the Cloud Pak for Data software that is installed, for example, 4.6.3.
    serviceId
    One of speech-to-text or text-to-speech.
    display_name
    The name that you want to use for the service instance. This name is displayed in the Instances page of the Cloud Pak for Data web client. The name can contain alphanumeric characters, spaces, dashes, underscores, and periods. In the example, the display_name is ${CUSTOM_RESOURCE_SPEECH}-test-instance.

  2. Use the following command to create the service instance. For more information about the service-instance create command, see service-instance create.

    cpd-cli service-instance create \
--profile <cpd-configuration-profile-name> --from-source <filename.json>

    where

    <cpd-configuration-profile-name>
    Specify the Cloud Pak for Data configuration profile that you created as a prerequisite step. For example, cpd-admin-profile.
    <filename.json>
    Specify the file path to the JSON file that you created in the previous step.

    For example, the following command creates a service instance with the values cpd-admin-profile and ./speech-instance.json:

    cpd-cli service-instance create \
--profile cpd-admin-profile --from-source ./speech-instance.json
  3. You must use one of the following approaches to obtain a bearer token that authorizes you to send API requests to the service instance:

Verifying a service instance

Use the URL and bearer token for your new instance to verify that your service and instance are working properly. See the API references for the services to learn more about their programming interfaces:

Use the commands for the microservices that you installed. Replace <token> with your bearer token and <url> with the URL for your service instance. The <url> has the form:

https://<host>/<service_id>/<deployment_id>/instances/<service_instance_id>/api

For example:

https://cpd-zen.example.com/speech-to-text/zen-speech-cr/instances/1674669735630400/api

  • For the Speech to Text runtime microservice (sttRuntime), use the HTTP GET /v1/models method to list the models that are available with the service. A successful command returns a list of the models that you installed for the service.

    curl -X GET \
  --header "Authorization: Bearer <token>" \
  "<url>/v1/models"

  • For the Speech to Text asynchronous HTTP microservice (sttAsync), use the HTTP GET /v1/recognitions method to list the status of asynchronous jobs for the service instance. A successful command returns an empty list of recognitions because no jobs exist for the new instance.

    curl -X GET \
  --header "Authorization: Bearer <token>" \
  "<url>/v1/recognitions"

  • For the Speech to Text customization microservice (sttCustomization), use the HTTP GET /v1/customizations method to list the custom language models for the service instance. A successful command returns an empty list of customizations because no custom language models exist for the new instance.

    curl -X GET \
  --header "Authorization: Bearer <token>" \
  "<url>/v1/customizations"

  • For the Text to Speech runtime microservice (ttsRuntime), use the HTTP GET /v1/voices method to list the voices that are available with the service. A successful command returns a list of the voices that you installed for the service.

    curl -X GET \
  --header "Authorization: Bearer <token>" \
  "<url>/v1/voices"

  • For the Text to Speech customization microservice (ttsCustomization), use the HTTP GET /v1/customizations method to list the custom models for the service instance. A successful command returns an empty list of customizations because no custom models exist for the new instance.

    curl -X GET \
  --header "Authorization: Bearer <token>" \
  "<url>/v1/customizations"