Batch Syntheses - List

Service:: Azure AI Services

API Version:: 2024-04-01

Gets the list of batch syntheses.

GET {endpoint}/texttospeech/batchsyntheses?api-version=2024-04-01

With optional parameters:

GET {endpoint}/texttospeech/batchsyntheses?skip={skip}&maxpagesize={maxpagesize}&api-version=2024-04-01

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	Supported Cognitive Services endpoints (protocol and hostname, for example: https://eastus.api.cognitive.microsoft.com).
api-version	query	True	string minLength: 1	The API version to use for this operation.
maxpagesize	query		integer (int32)	The maximum number of result items to include in a single response.
skip	query		integer (int32)	The number of result items to skip.

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string	Provide your cognitive services subscription key here.

Responses

Name	Type	Description
200 OK	PaginatedBatchSynthesis	Success
Other Status Codes	ErrorResponse	An error occurred. Headers x-ms-error-code: string

Name

Type

Description

200 OK

PaginatedBatchSynthesis

Success

Other Status Codes

ErrorResponse

An error occurred.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Provide your cognitive services subscription key here.

Type: apiKey
In: header

Examples

Create a project

Sample request

HTTP

GET {endpoint}/texttospeech/batchsyntheses?api-version=2024-04-01

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "my-batch-synthesis-job-text-input-1",
      "status": "Succeeded",
      "createdDateTime": "2024-03-15T06:19:18.0059236Z",
      "lastActionDateTime": "2024-03-15T06:19:19.0306365",
      "inputKind": "PlainText",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "synthesisConfig": {
        "voice": "en-US-JennyNeural"
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-batch-synthesis-job-text-input-1/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-batch-synthesis-job-ssml-input-1",
      "status": "Succeeded",
      "createdDateTime": "2024-03-15T06:03:33.808822Z",
      "lastActionDateTime": "2024-03-15T06:03:34.9367114",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": true,
        "wordBoundaryEnabled": true,
        "sentenceBoundaryEnabled": true,
        "destinationContainerUrl": "https://contoso.blob.core.windows.net/default?sv=2021-04-10&st=2024-03-15T04%3A47%3A54Z&se=2025-03-16T04%3A47%3A00Z&sr=c&sp=racwdl&sig=Masked",
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "29f2105f997c4bfea176d39d05ff201e/my-batch-synthesis-job-ssml-input-1",
        "summary": "29f2105f997c4bfea176d39d05ff201e/my-batch-synthesis-job-ssml-input-1/summary.json"
      }
    }
  ],
  "nextLink": "https://eastus.api.cognitive.microsoft.com/texttospeech/batchsynthesises?skip=0&maxpagesize=2&api-version=2024-04-01"
}

Definitions

Name	Description
BatchSynthesis	Bath synthesis task.
BatchSynthesisBackgroundAudioDefinition	Background audio setting.
BatchSynthesisBillingDetails	Bath synthesis billing details.
BatchSynthesisConfig	Text-to-speech configuration for plain text input.
BatchSynthesisError	Batch Synthesis Error.
BatchSynthesisInput	Batch Synthesis input.
BatchSynthesisOutputs	Batch Synthesis output.
BatchSynthesisProperties	Detailed properties of batch synthesis task.
Error	The error object.
ErrorCode	Top-level error code
ErrorResponse	Error response.
InnerError	An object containing more specific information about the error.
InputKind	Input text kind.
PaginatedBatchSynthesis	Paginated batch synthesis task list
Status	Status of a resource.

BatchSynthesis

Object

Bath synthesis task.

Name	Type	Description
createdDateTime	string (date-time)	The time-stamp when the object was created.
customVoices	object	The custom voice map of voice name and deployment ID.
description	string	The description of the batch synthesis task.
id	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Resource id
inputKind	InputKind	Input text kind.
inputs	BatchSynthesisInput[]	Text or SSML inputs, it's allowed up to 10000 items.
lastActionDateTime	string (date-time)	The time-stamp when the current status was entered.
outputs	BatchSynthesisOutputs	Batch Synthesis output.
properties	BatchSynthesisProperties	Detailed properties of batch synthesis task.
status	Status	Status of a resource.
synthesisConfig	BatchSynthesisConfig	Text-to-speech configuration for plain text input.

BatchSynthesisBackgroundAudioDefinition

Object

Background audio setting.

Name	Type	Description
fadein	integer (int64)	The fadein value of background audio. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.
fadeout	integer (int64)	The fadeout value of background audio. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.
src	string (uri)	Source of audio file. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.
volume	number (double)	The volume value of background audio. Reference https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#add-background-audio.

BatchSynthesisBillingDetails

Object

Bath synthesis billing details.

Name	Type	Description
aoaiCharacters	integer (int64)	The number of billable characters for AOAI voices in the input file.
aoaiHDCharacters	integer (int64)	The number of billable characters for AOAI HD voices in the input file.
customNeuralCharacters	integer (int64)	The number of billable characters for custom neural voices in the input file.
neuralCharacters	integer (int64)	The number of billable characters for prebuilt neural voices in the input file.
personalVoiceCharacters	integer (int64)	The number of billable characters for personal voices in the input file.

BatchSynthesisConfig

Object

Text-to-speech configuration for plain text input.

Name	Type	Description
backgroundAudio	BatchSynthesisBackgroundAudioDefinition	Background audio setting.
pitch	string	Pitch for PlainText input. For supported values, see https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#adjust-prosody.
rate	string	Speaking rate for PlainText input. For supported values, see https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#adjust-prosody.
style	string	Style name for PlainText input.
voice	string minLength: 1	Voice name for PlainText input. You can find platform voice list here https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts.
volume	string	Volume for PlainText input. For supported values, see https://learn.microsoft.com/azure/ai-services/speech-service/speech-synthesis-markup-voice#adjust-prosody.

BatchSynthesisError

Object

Batch Synthesis Error.

Name	Type	Description
code	string	Top level error code
message	string	Error message

BatchSynthesisInput

Object

Batch Synthesis input.

Name	Type	Description
content	string minLength: 1	It could be SSML or plain text.

BatchSynthesisOutputs

Object

Batch Synthesis output.

Name	Type	Description
result	string	sas url of the result file. It would be relative path when "destinationContainerUrl" is specified.
summary	string	When BatchSynthesisProperties.decompressOutputFiles is true, job summary file path will be provided here.

BatchSynthesisProperties

Object

Detailed properties of batch synthesis task.

Name	Type	Description
billingDetails	BatchSynthesisBillingDetails	Bath synthesis billing details.
concatenateResult	boolean	Whether synthesis result is concatenated.
decompressOutputFiles	boolean	Whether synthesis result is decompressed in target container. It only take effect when "destinationContainerUrl" is specified or "BYOS" is configured.
destinationContainerUrl	string (uri)	The requested destination container. It is an URL with Service adhoc SAS to a writeable container in Azure Blob storage.
destinationPath	string	The destination path in destination container, default to null, it only works when "DestinationContainerUrl" is specified, the final path prefix of outputs should be {DestinationPath}/{TaskId}/, or {TaskId} if not specified.
durationInMilliseconds	integer (int32)	The generated audio duration in milliseconds.
error	BatchSynthesisError	Batch Synthesis Error.
failedAudioCount	integer (int32)	The number of failed audios.
outputFormat	string	The requested audio output format. Reference https://learn.microsoft.com/azure/ai-services/speech-service/batch-synthesis-properties#batch-synthesis-properties.
sentenceBoundaryEnabled	boolean	Whether the sentence boundary output will be generated.
sizeInBytes	integer (int64)	The generated audio size in bytes.
succeededAudioCount	integer (int32)	The number of succeeded audios.
timeToLiveInHours	integer (int32)	How long the batch task will be kept in the system after it has completed. Once the batch task reaches the time to live after completion (succeeded or failed) it will be automatically deleted. The longest supported duration is 744 hours (31 days). The default value is 744 hours.
wordBoundaryEnabled	boolean	Whether the word boundary output will be generated.

Error

Object

The error object.

Name	Type	Description
code	ErrorCode	Top-level error code
details	Error[]	Additional supportive details regarding the error and/or expected policies.
innererror	InnerError	An object containing more specific information about the error.
message	string	High level error message.
target	string	The source of the error.

ErrorCode

Enumeration

Top-level error code

Value	Description
BadRequest
BadArgument
Unauthorized
Forbidden
NotFound
UnsupportedMediaType
TooManyRequests
InternalServerError
ServiceUnavailable

ErrorResponse

Object

Error response.

Name	Type	Description
error	Error	The error object.

InnerError

Object

An object containing more specific information about the error.

Name	Type	Description
code	string	Detailed error code to help diagnostic.
innererror	InnerError	An object containing more specific information about the error.
message	string	Detailed error message.
target	string	The source of the error.

InputKind

Enumeration

Input text kind.

Value	Description
PlainText
SSML

PaginatedBatchSynthesis

Object

Paginated batch synthesis task list

Name	Type	Description
nextLink	string (uri)	Link to next page.
value	BatchSynthesis[]	Bath synthesis tasks.

Status

Enumeration

Status of a resource.

Value	Description
NotStarted
Running
Succeeded
Failed

Share via

Batch Syntheses - List

URI Parameters

Request Header

Responses

Security

Ocp-Apim-Subscription-Key

Examples

Create a project

Sample request

Sample response

Definitions

BatchSynthesis

BatchSynthesisBackgroundAudioDefinition

BatchSynthesisBillingDetails

BatchSynthesisConfig

BatchSynthesisError

BatchSynthesisInput

BatchSynthesisOutputs

BatchSynthesisProperties

Error

ErrorCode

ErrorResponse

InnerError

InputKind

PaginatedBatchSynthesis

Status