Batch Syntheses - List

Service:: Azure AI Services

API Version:: 2024-08-01

Gets the list of batch syntheses.

GET {endpoint}/avatar/batchsyntheses?api-version=2024-08-01

With optional parameters:

GET {endpoint}/avatar/batchsyntheses?skip={skip}&maxpagesize={maxpagesize}&api-version=2024-08-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}/avatar/batchsyntheses?api-version=2024-08-01

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "talking-avatar-batch-synthesis-job-2",
      "status": "Succeeded",
      "createdDateTime": "2024-03-15T10:31:43.7134142Z",
      "lastActionDateTime": "2024-03-15T10:31:48.1575987",
      "inputKind": "PlainText",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "sizeInBytes": 493133,
        "durationInMilliseconds": 3530,
        "succeededCount": 1,
        "failedCount": 0,
        "billingDetails": {
          "neuralCharacters": 42,
          "talkingAvatarDurationSeconds": 3
        }
      },
      "synthesisConfig": {
        "voice": "en-us-JennyNeural"
      },
      "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "casual-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/3e8138d91be947bd9e076a4cf58a20f8/talking-avatar-batch-synthesis-job-2/0001.mp4?[token redacted]",
        "summary": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/3e8138d91be947bd9e076a4cf58a20f8/talking-avatar-batch-synthesis-job-2/summary.json?[token redacted]"
      }
    },
    {
      "id": "talking-avatar-batch-synthesis-job-1",
      "status": "Succeeded",
      "createdDateTime": "2024-03-15T10:28:23.7702311Z",
      "lastActionDateTime": "2024-03-15T10:28:46.363789",
      "inputKind": "PlainText",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "sizeInBytes": 1060360,
        "durationInMilliseconds": 3530,
        "succeededCount": 1,
        "failedCount": 0,
        "billingDetails": {
          "neuralCharacters": 34,
          "talkingAvatarDurationSeconds": 3
        }
      },
      "synthesisConfig": {
        "voice": "zh-CN-XiaoxiaoNeural"
      },
      "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "casual-sitting",
        "videoFormat": "Webm",
        "videoCodec": "vp9",
        "subtitleType": "soft_embedded",
        "backgroundColor": "transparent",
        "videoCrop": {
          "topLeft": {
            "x": 100,
            "y": 100
          },
          "bottomRight": {
            "x": 1820,
            "y": 1080
          }
        },
        "bitrateKbps": 2000,
        "customized": false
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/3e8138d91be947bd9e076a4cf58a20f8/talking-avatar-batch-synthesis-job-1/0001.webm?[token redacted]",
        "summary": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/3e8138d91be947bd9e076a4cf58a20f8/talking-avatar-batch-synthesis-job-1/summary.json?[token redacted]"
      }
    }
  ],
  "nextLink": "https://eastus.api.cognitive.microsoft.com/avatar/batchsyntheses/?maxpagesize=2&skip=2&api-version=2024-08-01"
}

Definitions

Name	Description
BatchAvatarConfig	Avatar configuration.
BatchAvatarCoordinateDefinition	Coordinate definition
BatchAvatarVideoCropDefinition	Only keep the region defined by this object in original Avatar output video.
BatchSynthesis	Batch synthesis task.
BatchSynthesisBillingDetails	Batch 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 kind.
PaginatedBatchSynthesis	Paginated batch synthesis task list
Status	Status of a resource.

BatchAvatarConfig

Object

Avatar configuration.

Name	Type	Description
avatarPosition	BatchAvatarCoordinateDefinition	Coordinate definition
avatarSize	BatchAvatarCoordinateDefinition	Coordinate definition
backgroundColor	string	The talking avatar background color.
backgroundImage	string	The talking avatar background image.
bitrateKbps	integer (int64)	The bitrate of video output settings for talking avatar.
customized	boolean	Whether the avatar character is a custom avatar or not.
resolution	BatchAvatarCoordinateDefinition	Coordinate definition
subtitleType	string	The talking avatar subtitle type.
talkingAvatarCharacter	string minLength: 1	The talking avatar character name. e.g., Lisa.
talkingAvatarStyle	string	The talking avatar character style. e.g., casual-sitting.
videoCodec	string	The output video codec.
videoCrop	BatchAvatarVideoCropDefinition	Only keep the region defined by this object in original Avatar output video.
videoFormat	string	The output video format.

BatchAvatarCoordinateDefinition

Object

Coordinate definition

Name	Type	Description
x	number (double)	Gets or sets the x-axis.
y	number (double)	Gets or sets the y-axis.

BatchAvatarVideoCropDefinition

Object

Only keep the region defined by this object in original Avatar output video.

Name	Type	Description
bottomRight	BatchAvatarCoordinateDefinition	Coordinate definition
topLeft	BatchAvatarCoordinateDefinition	Coordinate definition

BatchSynthesis

Object

Batch synthesis task.

Name	Type	Description
avatarConfig	BatchAvatarConfig	Avatar configuration.
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 kind.
inputs	BatchSynthesisInput[]	Text or SSML inputs, it's allowed up to 1000 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.

BatchSynthesisBillingDetails

Object

Batch 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.
talkingAvatarDurationSeconds	integer (int64)	The duration of the talking avatar generated video.

BatchSynthesisConfig

Object

Text-to-speech configuration for plain text input.

Name	Type	Description
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	Input content. 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	Job summary file path will be provided here.

BatchSynthesisProperties

Object

Detailed properties of batch synthesis task.

Name	Type	Default value	Description
billingDetails	BatchSynthesisBillingDetails		Batch synthesis billing details.
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 video duration in milliseconds.
error	BatchSynthesisError		Batch Synthesis Error.
failedCount	integer (int32)		The number of failed videos.
sizeInBytes	integer (int64)		The generated video size in bytes.
succeededCount	integer (int32)		The number of succeeded videos.
timeToLiveInHours	integer (int32)	774	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.

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 kind.

Value	Description
PlainText
SSML

PaginatedBatchSynthesis

Object

Paginated batch synthesis task list

Name	Type	Description
nextLink	string (uri)	Link to next page.
value	BatchSynthesis[]	Batch 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

BatchAvatarConfig

BatchAvatarCoordinateDefinition

BatchAvatarVideoCropDefinition

BatchSynthesis

BatchSynthesisBillingDetails

BatchSynthesisConfig

BatchSynthesisError

BatchSynthesisInput

BatchSynthesisOutputs

BatchSynthesisProperties

Error

ErrorCode

ErrorResponse

InnerError

InputKind

PaginatedBatchSynthesis

Status