Synthesize Speech (Async)

You submit text, the server immediately returns a long-running operation, and synthesis runs in the background. Poll the operation until it is done, then download the finished audio (and optional timestamps) from time-limited signed URLs.

Best for long-form content — audiobooks, podcasts, video voiceovers — or any batch pipeline where you don't want to hold an HTTP connection open for the duration of synthesis.

How it works

# 1. Submit — returns an operation name
OPERATION=$(curl -s 'https://api.inworld.ai/tts/v1/voice:synthesizeAsync' \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Hello, world! What a wonderful day to be a text-to-speech model!",
    "voiceId": "Dennis",
    "modelId": "inworld-tts-2",
    "audioConfig": { "audioEncoding": "MP3" },
    "timestampType": "WORD"
  }' | jq -r '.name')

# 2. Poll until done: true
until curl -s "https://api.inworld.ai/lro/v1alpha/$OPERATION" \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  | tee operation.json | jq -e '.done == true' > /dev/null; do
  sleep 5
done

# 3. Download (signed URLs — no Authorization header)
curl -s -o output.mp3 "$(jq -r '.response.audioUri' operation.json)"
curl -s -o timestamps.json "$(jq -r '.response.timestampsUri' operation.json)"

import time

import requests

BASE = "https://api.inworld.ai"
HEADERS = {"Authorization": "Basic <api-key>"}

# 1. Submit
operation = requests.post(
    f"{BASE}/tts/v1/voice:synthesizeAsync",
    headers=HEADERS,
    json={
        "text": "Hello, world! What a wonderful day to be a text-to-speech model!",
        "voiceId": "Dennis",
        "modelId": "inworld-tts-2",
        "audioConfig": {"audioEncoding": "MP3"},
        "timestampType": "WORD",
    },
).json()

# 2. Poll
while not operation.get("done"):
    time.sleep(5)
    operation = requests.get(
        f"{BASE}/lro/v1alpha/{operation['name']}", headers=HEADERS
    ).json()

# 3. Download (signed URLs — no Authorization header)
if "error" in operation:
    raise RuntimeError(f"Synthesis failed: {operation['error']['message']}")

result = operation["response"]
open("output.mp3", "wb").write(requests.get(result["audioUri"]).content)
if "timestampsUri" in result:  # present only when timestampType was requested
    timestamps = requests.get(result["timestampsUri"]).json()

When a job requests timestamps

A job that sets timestampType needs alignment to succeed as well as synthesis. If alignment cannot be produced, the whole operation fails and carries an error — async never returns an audioUri with timestampsUri quietly missing, because a job that asked for timing and got none is not the result that was asked for.

Timestamp availability is tracked separately from synthesis, so a language can in principle synthesize while alignment for it is unavailable. Wherever that is true you find out at submit — never after paying for audio you cannot use due to the lack of timestamps. The request is rejected before any job exists:

INVALID_ARGUMENT: timestamps are not available for language 'zz-ZZ'.
Omit timestamp_type to synthesize audio without them, or use a supported language.

Nothing is created, nothing is charged, and no concurrency slot is used. The error names the language, so you do not need to check anything in advance: if a job is accepted, timestamps are available for it. Drop timestampType if you want the audio without timing.

A job that passes submit can still fail during synthesis. Two outcomes are worth telling apart, because only one is worth retrying:

Listing your jobs

Persist the operation name from every submit response — it is the primary handle for polling. If you do lose one (a crash between submit and saving the name, a redeploy), list operations across all of your jobs with - in place of the job id:

# Running async jobs only; drop the filter to include finished ones
curl -s "https://api.inworld.ai/lro/v1alpha/ttsAsyncJobs/-/operations?filter=-done" \
  --header "Authorization: Basic $INWORLD_API_KEY"

The workspace is resolved from your API key, so you never have to supply a workspace id. A few things to know:

• filter=-done (or NOT done, or done=false) returns only running jobs; filter=done (or done=true) only finished ones.
• Results are unordered and cover roughly the last 7 days — operations expire together with their results.
• Paginate with pageToken until a response has no nextPageToken. A short or even empty page can still be followed by more results, so the absent token — not page size — is the end signal.

The same shape works for batch jobs via ttsBatchJobs/-. The fully qualified form — workspaces/{workspace}/ttsAsyncJobs/-/operations, with the workspace id taken from the first path segment of any operation name — is also accepted, and is what Operation.name always carries.

Limits

API Reference

Next Steps