curl --location 'https://api.inworld.ai/tts/v1/voice:synthesizeBatch' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"customId": "chapter-01",
"request": {
"text": "The first chapter begins on a quiet morning.",
"voiceId": "Ashley",
"modelId": "inworld-tts-2",
"audioConfig": { "audioEncoding": "MP3" },
"timestampType": "WORD"
}
},
{
"customId": "chapter-02",
"request": {
"text": "The second chapter opens with a storm at sea.",
"voiceId": "Dennis",
"modelId": "inworld-tts-2",
"audioConfig": { "audioEncoding": "MP3" }
}
}
]
}'import requests
url = "https://api.inworld.ai/tts/v1/voice:synthesizeBatch"
headers = {"Authorization": "Basic <api-key>", "Content-Type": "application/json"}
def item(custom_id, text, voice_id):
return {
"customId": custom_id,
"request": {
"text": text,
"voiceId": voice_id,
"modelId": "inworld-tts-2",
"audioConfig": {"audioEncoding": "MP3"},
},
}
payload = {"items": [
item("chapter-01", "The first chapter begins on a quiet morning.", "Ashley"),
item("chapter-02", "The second chapter opens with a storm at sea.", "Dennis"),
]}
operation = requests.post(url, json=payload, headers=headers).json()
print(operation["name"]) # poll this via GET /lro/v1alpha/{name}const url = 'https://api.inworld.ai/tts/v1/voice:synthesizeBatch';
const item = (customId, text, voiceId) => ({
customId,
request: {
text,
voiceId,
modelId: 'inworld-tts-2',
audioConfig: { audioEncoding: 'MP3' },
},
});
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': 'Basic <api-key>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
items: [
item('chapter-01', 'The first chapter begins on a quiet morning.', 'Ashley'),
item('chapter-02', 'The second chapter opens with a storm at sea.', 'Dennis'),
],
}),
});
const operation = await response.json();
console.log(operation.name); // poll this via GET /lro/v1alpha/{name}{
"name": "workspaces/{workspace}/ttsBatchJobs/9e03dcb0-2ad5-483b-9e61-962f3a9bb430/operations/1786040024834-Wpj18s",
"metadata": null,
"done": false
}{
"code": 5,
"message": "Unknown voice: John not found!",
"details": []
}Synthesize speech (batch)
Submit many independent synthesis requests as one background job and immediately receive a long-running operation. Poll the operation via the Get operation endpoint until done is true, then download the results file named by resultsUri — it lists every item’s outcome, keyed by the customId you assigned. Each item’s request is an ordinary synthesis request, validated exactly as the async endpoint would validate it; one invalid item rejects the whole batch at submit. That includes timestampType in a language without alignment support — like async jobs, a batch item never returns audio with requested timestamps silently missing.
curl --location 'https://api.inworld.ai/tts/v1/voice:synthesizeBatch' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"customId": "chapter-01",
"request": {
"text": "The first chapter begins on a quiet morning.",
"voiceId": "Ashley",
"modelId": "inworld-tts-2",
"audioConfig": { "audioEncoding": "MP3" },
"timestampType": "WORD"
}
},
{
"customId": "chapter-02",
"request": {
"text": "The second chapter opens with a storm at sea.",
"voiceId": "Dennis",
"modelId": "inworld-tts-2",
"audioConfig": { "audioEncoding": "MP3" }
}
}
]
}'import requests
url = "https://api.inworld.ai/tts/v1/voice:synthesizeBatch"
headers = {"Authorization": "Basic <api-key>", "Content-Type": "application/json"}
def item(custom_id, text, voice_id):
return {
"customId": custom_id,
"request": {
"text": text,
"voiceId": voice_id,
"modelId": "inworld-tts-2",
"audioConfig": {"audioEncoding": "MP3"},
},
}
payload = {"items": [
item("chapter-01", "The first chapter begins on a quiet morning.", "Ashley"),
item("chapter-02", "The second chapter opens with a storm at sea.", "Dennis"),
]}
operation = requests.post(url, json=payload, headers=headers).json()
print(operation["name"]) # poll this via GET /lro/v1alpha/{name}const url = 'https://api.inworld.ai/tts/v1/voice:synthesizeBatch';
const item = (customId, text, voiceId) => ({
customId,
request: {
text,
voiceId,
modelId: 'inworld-tts-2',
audioConfig: { audioEncoding: 'MP3' },
},
});
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': 'Basic <api-key>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
items: [
item('chapter-01', 'The first chapter begins on a quiet morning.', 'Ashley'),
item('chapter-02', 'The second chapter opens with a storm at sea.', 'Dennis'),
],
}),
});
const operation = await response.json();
console.log(operation.name); // poll this via GET /lro/v1alpha/{name}{
"name": "workspaces/{workspace}/ttsBatchJobs/9e03dcb0-2ad5-483b-9e61-962f3a9bb430/operations/1786040024834-Wpj18s",
"metadata": null,
"done": false
}{
"code": 5,
"message": "Unknown voice: John not found!",
"details": []
}Authorizations
Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY. You can create a key in one command with the Inworld CLI: inworld workspace add-key.
Body
A set of independent synthesis requests submitted as one job. Items may each use a different voice, model, language, and audio format.
The requests to synthesize, between 1 and 10000. The whole request must also fit the 16 MiB message limit, which caps the aggregate around 4M characters — the item ceiling is only reachable when items are short.
1 - 10000 elementsShow child attributes
Show child attributes
Response
The batch was accepted. The returned operation is not yet done; poll it to track progress.
A google.longrunning.Operation tracking an asynchronous or batch synthesis job.
Server-assigned operation resource name, in the format workspaces/{workspace}/ttsAsyncJobs/{job}/operations/{operation} for async jobs or workspaces/{workspace}/ttsBatchJobs/{batch}/operations/{operation} for batch jobs. Pass it verbatim as the path of the Get operation endpoint to poll for completion.
"workspaces/{workspace}/ttsAsyncJobs/8f14e45f-ceea-4673-93d8-04f724c8a1b2/operations/1784837936461-p0sEhU"
Service-specific metadata associated with the operation. Not populated for TTS jobs yet; job metadata is planned for a later release, so do not write code that depends on this field staying absent.
Show child attributes
Show child attributes
If false, the job is still running. If true, the job has finished and exactly one of error or response is set.
Show child attributes
Show child attributes
Set when the job succeeded. Its @type identifies which kind: an async job carries SynthesizeSpeechAsyncResponse, a batch job SynthesizeSpeechBatchResponse.
- Option 1
- Option 2
Show child attributes
Show child attributes
Was this page helpful?