Synthesize speech (async)

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.

The text to be synthesized into speech. Maximum input of 100,000 characters. On-Demand accounts are capped at 10,000 characters per job. Required without script; omit it when sending a script. For scripts, the limit applies to the sum of the utterance texts.

The ID of the voice to use for synthesizing speech. Set either voiceId or voiceDesign, not both. Omit this field when sending script; select a stored voice in each utterance’s voiceConfig instead.

Configurations to use when synthesizing speech.

The ID of the model to use for synthesizing speech. See Models for available models.

BCP-47 language tag (e.g., en-US, fr-FR, ja-JP) specifying the language that the given voice should speak the text in. Matching is case- and separator-insensitive for standard two-part tags (en-gb, EN_GB, and en-GB are equivalent); longer tags with extension subtags must match a catalog entry exactly. If a localized voice prompt exists for the language, it will be used. When omitted, the original voice prompt will be used and the language will be auto-detected from the input text. If an invalid language code is provided, an error will be returned.

See Languages for more details.

Only supported by `inworld-tts-2`. The field is ignored on other models.

Controls how varied the output is.

• DELIVERY_MODE_UNSPECIFIED: Defaults to BALANCED behavior.
• STABLE: Optimizes for more consistent, predictable output.
• BALANCED: Balanced between stability and diversity.
• CREATIVE: Optimizes for increased emotional range and variation.

Ignored on `inworld-tts-2`. Use [`deliveryMode`](#body-delivery-mode) instead.

Determines the degree of randomness when sampling audio tokens to generate the response.

Defaults to 1.0. Accepts values between 0 (exclusive) and 2 (inclusive). Higher values will make the output more random and can lead to more expressive results. Lower values will make it more deterministic. If 0 is provided, the default value will be used.

For the most stable results, we recommend using the default value.

Controls timestamp metadata returned with the audio. When enabled, the response includes timing arrays, which can be useful for word-highlighting, karaoke-style captions, and lipsync.

• WORD: Output arrays under timestampInfo.wordAlignment (words, wordStartTimeSeconds, wordEndTimeSeconds).
• CHARACTER: Output arrays under timestampInfo.characterAlignment (characters, characterStartTimeSeconds, characterEndTimeSeconds).
• TIMESTAMPTYPEUNSPECIFIED: Do not compute alignment; timestamp arrays will be empty or omitted.

Phonetic details: phoneticDetails is currently only returned for WORD alignment (not CHARACTER).

Latency note: Alignment adds additional computation. Enabling alignment can increase latency.

When enabled, text normalization automatically expands and standardizes things like numbers, dates, times, and abbreviations before converting them to speech. For example, Dr. Smith becomes Doctor Smith, and 3/10/25 is spoken as March tenth, twenty twenty-five. Turning this off may reduce latency, but the speech output will read the text exactly as written. Defaults to automatically deciding whether to apply text normalization.

When true, applies denoising to the synthesized audio to reduce background noise and artifacts, improving the overall audio quality of the generation. Defaults to false (no denoising).

Context for the current synthesis request. Supplying the text of earlier requests from the same session or conversation gives the model additional context and can improve the quality of the generation, especially for short or ambiguous input text. Context text is not billed. At most 5 previous requests, and their texts combined must not exceed 2,000 characters.

Omit this field when sending script; select a stored voice in each utterance’s voiceConfig instead.

When true, applies the workspace pronunciations saved on the Portal Custom Pronunciations page. No dictionary ID is needed: the API key identifies the workspace. Requires inworld-tts-2; set language to match the saved entries. If the saved pronunciations cannot be loaded, synthesis continues without them. Omit this field, even as false, when sending pronunciationDictionarySettings. See Custom pronunciations.

Selects saved pronunciation dictionaries for this request. Requires inworld-tts-2 and an explicit language matching the entries. When two selected dictionaries define the same word and language, the earlier one wins. Do not combine with enableCustomPronunciation, even when it is false.

Requests viseme (mouth-shape) timing for lip-sync, returned in timestampInfo.lipsyncAlignment. Its presence turns lip-sync on; an empty object is enough. Visemes are computed from the synthesized audio, so they add no latency and work with every model and language. Independent of timestampType: request them on their own or together with word or character timestamps. See the Lip-sync guide.

Ordered utterances for TTS-2. Replaces top-level text, voiceId, and voiceDesign. The endpoint’s text limit applies to the sum of the utterance texts. See Script synthesis.

Select one combined recording or separate utterance recordings. Omitted or OUTPUT_MODE_UNSPECIFIED means COMBINED. PER_UTTERANCE requires script. Both modes retain generation history. Async and batch per-utterance results require ZIP packaging.

Preview. Where the results go and how they are packaged. Omit it to have Inworld host them as per-file download URLs. See Results delivery.

Server-assigned operation resource name, in the format workspaces/{workspace}/ttsAsyncJobs/{job}/operations/{operation}. Pass it verbatim as the path of the Get operation endpoint to poll for completion.

Always null. An async job is a single unit of work and carries no progress metadata: done already says everything there is to know.

If false, the job is still running. If true, the job has finished and exactly one of error or response is set.

Set when the job succeeded: a SynthesizeSpeechAsyncResponse saying where the results are.