Deploy and use your voice model

Article
09/01/2023

After you've successfully created and trained your voice model, you deploy it to a custom neural voice endpoint.

Use the Speech Studio to add a deployment endpoint for your custom neural voice. You can use either the Speech Studio or text to speech REST API to suspend or resume a custom neural voice endpoint.

Note

You can create up to 50 endpoints with a standard (S0) Speech resource, each with its own custom neural voice.

To use your custom neural voice, you must specify the voice model name, use the custom URI directly in an HTTP request, and use the same Speech resource to pass through the authentication of the text to speech service.

Add a deployment endpoint

To create a custom neural voice endpoint:

Sign in to the Speech Studio.
Select Custom Voice > Your project name > Deploy model > Deploy model.
Select a voice model that you want to associate with this endpoint.
Enter a Name and Description for your custom endpoint.
Select Endpoint type according to your scenario. If your resource is in a supported region, the default setting for the endpoint type is High performance. Otherwise, if the resource is in an unsupported region, the only available option is Fast resume.
- High performance: Optimized for scenarios with real-time and high-volume synthesis requests, such as conversational AI, call-center bots. It takes around 5 minutes to deploy or resume an endpoint. For information about regions where the High performance endpoint type is supported, see the footnotes in the regions table.
- Fast resume: Optimized for audio content creation scenarios with less frequent synthesis requests. Easy and quick to deploy or resume an endpoint in under a minute. The Fast resume endpoint type is supported in all regions where text to speech is available.
Select Deploy to create your endpoint.

After your endpoint is deployed, the endpoint name appears as a link. Select the link to display information specific to your endpoint, such as the endpoint key, endpoint URL, and sample code. When the status of the deployment is Succeeded, the endpoint is ready for use.

Application settings

The application settings that you use as REST API request parameters are available on the Deploy model tab in Speech Studio.

The Endpoint key shows the Speech resource key the endpoint is associated with. Use the endpoint key as the value of your Ocp-Apim-Subscription-Key request header.
The Endpoint URL shows your service region. Use the value that precedes voice.speech.microsoft.com as your service region request parameter. For example, use eastus if the endpoint URL is https://eastus.voice.speech.microsoft.com/cognitiveservices/v1.
The Endpoint URL shows your endpoint ID. Use the value appended to the ?deploymentId= query parameter as the value of your endpoint ID request parameter.

Use your custom voice

The custom endpoint is functionally identical to the standard endpoint that's used for text to speech requests.

One difference is that the EndpointId must be specified to use the custom voice via the Speech SDK. You can start with the text to speech quickstart and then update the code with the EndpointId and SpeechSynthesisVoiceName.

var speechConfig = SpeechConfig.FromSubscription(speechKey, speechRegion);     
speechConfig.SpeechSynthesisVoiceName = "YourCustomVoiceName";
speechConfig.EndpointId = "YourEndpointId";

auto speechConfig = SpeechConfig::FromSubscription(speechKey, speechRegion);
speechConfig->SetSpeechSynthesisVoiceName("YourCustomVoiceName");
speechConfig->SetEndpointId("YourEndpointId");

SpeechConfig speechConfig = SpeechConfig.fromSubscription(speechKey, speechRegion);
speechConfig.setSpeechSynthesisVoiceName("YourCustomVoiceName");
speechConfig.setEndpointId("YourEndpointId");

SPXSpeechConfiguration *speechConfig = [[SPXSpeechConfiguration alloc] initWithSubscription:speechKey region:speechRegion];
speechConfig.speechSynthesisVoiceName = @"YourCustomVoiceName";
speechConfig.EndpointId = @"YourEndpointId";

speech_config = speechsdk.SpeechConfig(subscription=os.environ.get('SPEECH_KEY'), region=os.environ.get('SPEECH_REGION'))
speech_config.endpoint_id = "YourEndpointId"
speech_config.speech_synthesis_voice_name = "YourCustomVoiceName"

To use a custom neural voice via Speech Synthesis Markup Language (SSML), specify the model name as the voice name. This example uses the YourCustomVoiceName voice.

<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">
    <voice name="YourCustomVoiceName">
        This is the text that is spoken. 
    </voice>
</speak>

Switch to a new voice model in your product

Once you've updated your voice model to the latest engine version, or if you want to switch to a new voice in your product, you need to redeploy the new voice model to a new endpoint. Redeploying new voice model on your existing endpoint is not supported. After deployment, switch the traffic to the newly created endpoint. We recommend that you transfer the traffic to the new endpoint in a test environment first to ensure that the traffic works well, and then transfer to the new endpoint in the production environment. During the transition, you need to keep the old endpoint. If there are some problems with the new endpoint during transition, you can switch back to your old endpoint. If the traffic has been running well on the new endpoint for about 24 hours (recommended value), you can delete your old endpoint.

Note

If your voice name is changed and you are using Speech Synthesis Markup Language (SSML), be sure to use the new voice name in SSML.

Suspend and resume an endpoint

You can suspend or resume an endpoint, to limit spend and conserve resources that aren't in use. You won't be charged while the endpoint is suspended. When you resume an endpoint, you can continue to use the same endpoint URL in your application to synthesize speech.

You can suspend and resume an endpoint in Speech Studio or via the REST API.

Note

The suspend operation will complete almost immediately. The resume operation completes in about the same amount of time as a new deployment.

Suspend and resume an endpoint in Speech Studio

This section describes how to suspend or resume a custom neural voice endpoint in the Speech Studio portal.

Suspend endpoint

To suspend and deactivate your endpoint, select Suspend from the Deploy model tab in Speech Studio.
In the dialog box that appears, select Submit. After the endpoint is suspended, Speech Studio will show the Successfully suspended endpoint notification.

Resume endpoint

To resume and activate your endpoint, select Resume from the Deploy model tab in Speech Studio.
In the dialog box that appears, select Submit. After you successfully reactivate the endpoint, the status will change from Suspended to Succeeded.

Suspend and resume endpoint via REST API

This section will show you how to get, suspend, or resume a custom neural voice endpoint via REST API.

Get endpoint

Get the endpoint by endpoint ID. The operation returns details about an endpoint such as model ID, project ID, and status.

For example, you might want to track the status progression for suspend or resume operations. Use the status property in the response payload to determine the status of the endpoint.

The possible status property values are:

Status	Description
`NotStarted`	The endpoint hasn't yet been deployed, and it's not available for speech synthesis.
`Running`	The endpoint is in the process of being deployed or resumed, and it's not available for speech synthesis.
`Succeeded`	The endpoint is active and available for speech synthesis. The endpoint has been deployed or the resume operation succeeded.
`Failed`	The endpoint deploy or suspend operation failed. The endpoint can only be viewed or deleted in Speech Studio.
`Disabling`	The endpoint is in the process of being suspended, and it's not available for speech synthesis.
`Disabled`	The endpoint is inactive, and it's not available for speech synthesis. The suspend operation succeeded or the resume operation failed.

Tip

If the status is Failed or Disabled, check properties.error for a detailed error message. However, there won't be error details if the status is Disabled due to a successful suspend operation.

Get endpoint example

For information about endpoint ID, region, and Speech resource key parameters, see request parameters.

HTTP example:

GET api/texttospeech/v3.0/endpoints/<YourEndpointId> HTTP/1.1
Ocp-Apim-Subscription-Key: YourResourceKey
Host: <YourResourceRegion>.customvoice.api.speech.microsoft.com

cURL example:

curl -v -X GET "https://<YourResourceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>" -H "Ocp-Apim-Subscription-Key: <YourResourceKey >"

Response header example:

Status code: 200 OK

Response body example:

{
  "model": {
    "id": "a92aa4b5-30f5-40db-820c-d2d57353de44"
  },
  "project": {
    "id": "ffc87aba-9f5f-4bfa-9923-b98186591a79"
  },
  "properties": {},
  "status": "Succeeded",
  "lastActionDateTime": "2019-01-07T11:36:07Z",
  "id": "e7ffdf12-17c7-4421-9428-a7235931a653",
  "createdDateTime": "2019-01-07T11:34:12Z",
  "locale": "en-US",
  "name": "Voice endpoint",
  "description": "Example for voice endpoint"
}

Suspend endpoint

You can suspend an endpoint to limit spend and conserve resources that aren't in use. You won't be charged while the endpoint is suspended. When you resume an endpoint, you can use the same endpoint URL in your application to synthesize speech.

You suspend an endpoint with its unique deployment ID. The endpoint status must be Succeeded before you can suspend it.

Use the get endpoint operation to poll and track the status progression from Succeeded, to Disabling, and finally to Disabled.

Suspend endpoint example

For information about endpoint ID, region, and Speech resource key parameters, see request parameters.

HTTP example:

POST api/texttospeech/v3.0/endpoints/<YourEndpointId>/suspend HTTP/1.1
Ocp-Apim-Subscription-Key: YourResourceKey
Host: <YourResourceRegion>.customvoice.api.speech.microsoft.com
Content-Type: application/json
Content-Length: 0

cURL example:

curl -v -X POST "https://<YourResourceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>/suspend" -H "Ocp-Apim-Subscription-Key: <YourResourceKey >" -H "content-type: application/json" -H "content-length: 0"

Response header example:

Status code: 202 Accepted

For more information, see response headers.

Resume endpoint

When you resume an endpoint, you can use the same endpoint URL that you used before it was suspended.

You resume an endpoint with its unique deployment ID. The endpoint status must be Disabled before you can resume it.

Use the get endpoint operation to poll and track the status progression from Disabled, to Running, and finally to Succeeded. If the resume operation failed, the endpoint status will be Disabled.

Resume endpoint example

For information about endpoint ID, region, and Speech resource key parameters, see request parameters.

HTTP example:

POST api/texttospeech/v3.0/endpoints/<YourEndpointId>/resume HTTP/1.1
Ocp-Apim-Subscription-Key: YourResourceKey
Host: <YourResourceRegion>.customvoice.api.speech.microsoft.com
Content-Type: application/json
Content-Length: 0

cURL example:

curl -v -X POST "https://<YourResourceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>/resume" -H "Ocp-Apim-Subscription-Key: <YourResourceKey >" -H "content-type: application/json" -H "content-length: 0"

Response header example:

Status code: 202 Accepted

For more information, see response headers.

Parameters and response codes

Request parameters

You use these request parameters with calls to the REST API. See application settings for information about where to get your region, endpoint ID, and Speech resource key in Speech Studio.

Name	Location	Required	Type	Description
`YourResourceRegion`	Path	`True`	string	The Azure region the endpoint is associated with.
`YourEndpointId`	Path	`True`	string	The identifier of the endpoint.
`Ocp-Apim-Subscription-Key`	Header	`True`	string	The Speech resource key the endpoint is associated with.

Response headers

Status code: 202 Accepted

Name	Type	Description
`Location`	string	The location of the endpoint that can be used as the full URL to get endpoint.
`Retry-After`	string	The total seconds of recommended interval to retry to get endpoint status.

HTTP status codes

The HTTP status code for each response indicates success or common errors.

HTTP status code	Description	Possible reason
200	OK	The request was successful.
202	Accepted	The request has been accepted and is being processed.
400	Bad Request	The value of a parameter is invalid, or a required parameter is missing, empty, or null. One common issue is a header that is too long.
401	Unauthorized	The request isn't authorized. Check to make sure your Speech resource key or token is valid and in the correct region.
429	Too Many Requests	You've exceeded the quota or rate of requests allowed for your Speech resource.
502	Bad Gateway	Network or server-side issue. May also indicate invalid headers.

Deploy and use your voice model

Add a deployment endpoint

Application settings

Use your custom voice

Switch to a new voice model in your product

Suspend and resume an endpoint

Suspend and resume an endpoint in Speech Studio

Suspend endpoint

Resume endpoint

Suspend and resume endpoint via REST API

Get endpoint

Get endpoint example

Suspend endpoint

Suspend endpoint example

Resume endpoint

Resume endpoint example

Parameters and response codes

Request parameters

Response headers

HTTP status codes

Next steps

Feedback

Additional resources

Additional resources