Edit

Migrate code from Long Audio API to Batch synthesis API

  • Article

The Batch synthesis API (Preview) provides asynchronous synthesis of long-form text to speech. Benefits of upgrading from Long Audio API to Batch synthesis API, and details about how to do so, are described in the sections below.

Important

Batch synthesis API is currently in public preview. Once it's generally available, the Long Audio API will be deprecated.

Base path

You must update the base path in your code from /texttospeech/v3.0/longaudiosynthesis to /texttospeech/3.1-preview1/batchsynthesis. For example, to list synthesis jobs for your Speech resource in the eastus region, use https://eastus.customvoice.api.speech.microsoft.com/api/texttospeech/3.1-preview1/batchsynthesis instead of https://eastus.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/longaudiosynthesis.

Regions and endpoints

Batch synthesis API is available in all Speech regions.

The Long Audio API is limited to the following regions:

Region Endpoint
Australia East https://australiaeast.customvoice.api.speech.microsoft.com
East US https://eastus.customvoice.api.speech.microsoft.com
India Central https://centralindia.customvoice.api.speech.microsoft.com
South Central US https://southcentralus.customvoice.api.speech.microsoft.com
Southeast Asia https://southeastasia.customvoice.api.speech.microsoft.com
UK South https://uksouth.customvoice.api.speech.microsoft.com
West Europe https://westeurope.customvoice.api.speech.microsoft.com

Voices list

Batch synthesis API supports all text to speech voices and styles.

The Long Audio API is limited to the set of voices returned by a GET request to https://<endpoint>/api/texttospeech/v3.0/longaudiosynthesis/voices.

Text inputs

Batch synthesis text inputs are sent in a JSON payload of up to 500 kilobytes.

Long Audio API text inputs are uploaded from a file that meets the following requirements:

  • One plain text (.txt) or SSML text (.txt) file encoded as UTF-8 with Byte Order Mark (BOM). Don't use compressed files such as ZIP. If you have more than one input file, you must submit multiple requests.
  • Contains more than 400 characters for plain text or 400 billable characters for SSML text, and less than 10,000 paragraphs. For plain text, each paragraph is separated by a new line. For SSML text, each SSML piece is considered a paragraph. Separate SSML pieces by different paragraphs.

With Batch synthesis API, you can use any of the supported SSML elements, including the audio, mstts:backgroundaudio, and lexicon elements. The audio, mstts:backgroundaudio, and lexicon elements aren't supported by Long Audio API.

Audio output formats

Batch synthesis API supports all text to speech audio output formats.

The Long Audio API is limited to the following set of audio output formats. The sample rate for long audio voices is 24kHz, not 48kHz. Other sample rates can be obtained through upsampling or downsampling when synthesizing.

  • riff-8khz-16bit-mono-pcm
  • riff-16khz-16bit-mono-pcm
  • riff-24khz-16bit-mono-pcm
  • riff-48khz-16bit-mono-pcm
  • audio-16khz-32kbitrate-mono-mp3
  • audio-16khz-64kbitrate-mono-mp3
  • audio-16khz-128kbitrate-mono-mp3
  • audio-24khz-48kbitrate-mono-mp3
  • audio-24khz-96kbitrate-mono-mp3
  • audio-24khz-160kbitrate-mono-mp3

Getting results

With batch synthesis API, use the URL from the outputs.result property of the GET batch synthesis response. The results are in a ZIP file that contains the audio (such as 0001.wav), summary, and debug details.

Long Audio API text inputs and results are returned via two separate content URLs as shown in the following example. The one with "kind": "LongAudioSynthesisScript" is the input script submitted. The other one with "kind": "LongAudioSynthesisResult" is the result of this request. Both ZIP files can be downloaded from the URL in their links.contentUrl property.

Cleaning up resources

Batch synthesis API supports up to 200 batch synthesis jobs that don't have a status of "Succeeded" or "Failed". The Speech service will keep each synthesis history for up to 31 days, or the duration of the request timeToLive property, whichever comes sooner. The date and time of automatic deletion (for synthesis jobs with a status of "Succeeded" or "Failed") is equal to the lastActionDateTime + timeToLive properties.

The Long Audio API is limited to 20,000 requests for each Azure subscription account. The Speech service doesn't remove job history automatically. You must remove the previous job run history before making new requests that would otherwise exceed the limit.

Next steps