TextToSpeech
Synthesize speech (batch)
Inworld TTS API reference: submit many independent text-to-speech requests as one background batch job and download all results together.
/tts/v1/voice:synthesizeBatchResults file
When the batch finishes, the operation's response.resultsUri identifies the results. By default, it points to this JSON file, and each item's artifacts are pre-signed download URLs. For results delivered to your storage with outputConfig.resultsUri, or hosted with outputConfig.packaging: ZIP, it points to a zip archive. The JSON file is at response.resultsPath inside the archive, and each item's artifacts are paths within that archive.
failedItemsinteger
Number of items that failed. Omitted rather than sent as 0 when every item succeeded, so read it with a default.
resultsobject[]
One entry per submitted item, in submission order. Correlate entries by customId, not by position.
Show child attributes — results
audioUristring
Pre-signed download URL for this item's audio in the requested format. Present when results are packaged as files. Fetch it without an Authorization header before the response's expireTime. Absent when the item failed.
timestampsUristring
Pre-signed download URL for this item's timestamp alignment JSON, when the results are packaged as files. Present only when the item's request set timestampType or lipsyncConfig and the item succeeded. See Reading the timestamps document for its format.
audioPathstring
Path of this item's audio inside the archive, for example items/0.mp3, for COMBINED output when the results are packaged as a zip. Absent when the item failed.
timestampsPathstring
Path of this item's timestamp alignment JSON inside the archive, for example items/0.timestamps.json, for COMBINED output when the results are packaged as a zip. Present only when the item's request set timestampType or lipsyncConfig and the item succeeded. See Reading the timestamps document for its format.
errorobject
A status explaining why this item produced no audio, with a numeric code and a message. Absent when the item succeeded.
scriptResultobject
Present for PER_UTTERANCE output in the ZIP results document. Its utterances array lists utteranceIndex, audioPath, and optional timestampsPath for each utterance, in script order. Paths are relative to this results document; timestamps start at zero for each utterance. See Script synthesis.
Using saved pronunciations? See the pronunciation dictionaries guide.
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.
Show child attributes
Your key for this item, echoed into the results file. Required, and unique within the batch — it is the only thing correlating a result back to what you submitted. Treat it as opaque; the service never interprets it.
The synthesis request for this item, identical in shape to a synchronous request and subject to the same validation. On-Demand accounts are additionally capped at 10,000 characters across the whole batch.
Show child attributes
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.
Show child attributes
audioEncodingenum<string>default: "MP3"
The desired output format of the synthesized audio. Defaults to MP3.
LINEAR16: Uncompressed 16-bit signed little-endian samples (Linear PCM). For non-streaming, the WAV header is included in the response. For streaming, the WAV header is included in every audio chunk.MP3: MP3 audio.OGG_OPUS: Opus encoded audio wrapped in an ogg container. The result will be a file which can be played natively on Android, and in browsers (at least Chrome and Firefox). The quality of the encoding is considerably higher than MP3 while using approximately the same bitrate.ALAW: ALAW encoded audio. 8-bit companded PCM.MULAW: MULAW encoded audio. 8-bit companded PCM.FLAC: FLAC encoded audio. Lossless audio format.PCM: PCM audio. Uncompressed 16-bit signed little-endian samples with no WAV header.WAV: WAV audio. Uncompressed 16-bit signed little-endian samples. For non-streaming, the WAV header is included in the response. For streaming, the WAV header is included in the first audio chunk only.
Available options:LINEAR16MP3OGG_OPUSALAWMULAWFLACPCMWAV
Bits per second of the audio. Only for compressed audio formats (MP3, OGG_OPUS). The default is 128,000.
The synthesis sample rate (in hertz) for this audio. Accepts values within the range [8000, 48000]. Common sample rates include: 8000, 16000, 22050, 24000, 32000, 44100, 48000.
If you request a supported rate that differs from the model's native output rate, the service converts the audio to that rate. Conversion may reduce audio quality. The request fails if the chosen encoding does not support the rate, or if the rate exceeds a known native output rate.
When omitted, the default is 8,000 Hz for MULAW and ALAW. For other encodings, it is 48,000 Hz, capped at the model's native output rate when known.
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.
deliveryModeenum<string>default: "DELIVERY_MODE_UNSPECIFIED"
Only supported by `inworld-tts-2`. The field is ignored on other models.
Controls how varied the output is.
DELIVERY_MODE_UNSPECIFIED: Defaults toBALANCEDbehavior.STABLE: Optimizes for more consistent, predictable output.BALANCED: Balanced between stability and diversity.CREATIVE: Optimizes for increased emotional range and variation.
Available options:DELIVERY_MODE_UNSPECIFIEDSTABLEBALANCEDCREATIVE
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.
timestampTypeenum<string>default: "TIMESTAMP_TYPE_UNSPECIFIED"
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.
Available options:TIMESTAMP_TYPE_UNSPECIFIEDWORDCHARACTER
applyTextNormalizationenum<string>default: "APPLY_TEXT_NORMALIZATION_UNSPECIFIED"
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.
Available options:APPLY_TEXT_NORMALIZATION_UNSPECIFIEDONOFF
enhanceGenerationbooleandefault: false
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.
Show child attributes
Previous requests from the same session or conversation, in the order they were synthesized.
reasoningenum<string>default: "REASONING_UNSPECIFIED"
Supported by `inworld-tts-2` on Synthesize speech, Synthesize speech (streaming) and Synthesize speech (async). Support for Synthesize speech (batch) is coming soon.
Turns on Reasoning: before synthesis, a language model reads the text and writes a short steering instruction for it, or writes none when the text needs no direction. The instruction it applied is returned in reasoningInstruction. An inline [tag] in the text takes over from where it appears.
REASONING_UNSPECIFIED: Default. Reasoning doesn't run.REASONING_ON: Write an instruction for this request.
Available options:REASONING_UNSPECIFIEDREASONING_ON
Notes for Reasoning about what the text alone can't carry, such as the scene of an audiobook passage or the character in a roleplay. Read only when Reasoning runs. Never spoken and not billed. At most 600 characters; longer is rejected with INVALID_ARGUMENT. Put earlier lines of the conversation in previousRequests, not here.
Omit this field when sending script; select a stored voice in each utterance’s voiceConfig instead.
enableCustomPronunciationboolean
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.
pronunciationDictionarySettingsobject
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.
Show child attributes
One to three distinct dictionaries in priority order.
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.
Show child attributes
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.
Show child attributes
Utterances in playback order. The endpoint’s text limit applies to the sum of their texts.
Show child attributes
Show child attributes
Speaking rate for this voice or utterance. Omission inherits the matching voice default, then audioConfig.speakingRate.
deliveryModeenum<string>default: "DELIVERY_MODE_UNSPECIFIED"
Only supported by `inworld-tts-2`. The field is ignored on other models.
Controls how varied the output is.
DELIVERY_MODE_UNSPECIFIED: Defaults toBALANCEDbehavior.STABLE: Optimizes for more consistent, predictable output.BALANCED: Balanced between stability and diversity.CREATIVE: Optimizes for increased emotional range and variation.
Available options:DELIVERY_MODE_UNSPECIFIEDSTABLEBALANCEDCREATIVE
Optional defaults keyed by unique voiceId. Each utterance still requires its own voiceConfig.voiceId. Utterance settings override these defaults; omitted settings inherit request-level values.
Show child attributes
Speaking rate for this voice or utterance. Omission inherits the matching voice default, then audioConfig.speakingRate.
deliveryModeenum<string>default: "DELIVERY_MODE_UNSPECIFIED"
Only supported by `inworld-tts-2`. The field is ignored on other models.
Controls how varied the output is.
DELIVERY_MODE_UNSPECIFIED: Defaults toBALANCEDbehavior.STABLE: Optimizes for more consistent, predictable output.BALANCED: Balanced between stability and diversity.CREATIVE: Optimizes for increased emotional range and variation.
Available options:DELIVERY_MODE_UNSPECIFIEDSTABLEBALANCEDCREATIVE
outputModeenum<string>default: "COMBINED"
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.
Available options:OUTPUT_MODE_UNSPECIFIEDCOMBINEDPER_UTTERANCE
Preview. Where the whole batch's results go and how they are packaged. Set it here, at the top level: an item whose request sets outputConfig is rejected. Omit it to have Inworld host the results file and per-item download URLs. See Results delivery.
Show child attributes
A URL to an object in storage you own, pre-signed for an HTTP PUT: an Amazon S3 presigned URL, a Google Cloud Storage V4 signed URL, or an Azure SAS URL that grants write. The job uploads its results there as one zip archive, and nothing is retained by Inworld. The signature must stay valid for at least 12 hours after submit for an async job, and 48 hours for a batch. Omit it to have Inworld host the results for about 7 days. Required when the workspace has Zero Data Retention enabled: a job without it is refused with FAILED_PRECONDITION.
packagingenum<string>default: "PACKAGING_UNSPECIFIED"
How the results are packaged.
- ZIP: One zip archive holding
results.jsonbeside every artifact it names, by paths relative to it. The response names the archive inresultsUriand the document inresultsPath. - FILES: Each artifact as its own pre-signed download URL. Only for results Inworld hosts:
FILEStogether withresultsUriis rejected withINVALID_ARGUMENT. - PACKAGING_UNSPECIFIED:
ZIPwhenresultsUriis set,FILESotherwise.
Available options:PACKAGING_UNSPECIFIEDZIPFILES
Server-assigned operation resource name, in the format workspaces/{workspace}/ttsBatchJobs/{batch}/operations/{operation}. Pass it verbatim as the path of the Get operation endpoint to poll for completion.
SynthesizeSpeechBatchMetadata counting the items finished so far, present from the moment the batch is accepted through to the terminal response.
Show child attributes
Number of items in the batch. Fixed when the batch is accepted, so it is readable before any work starts.
Items synthesized successfully so far. A zero counter is spelled out as 0 on the submit response but omitted from the poll response, so read it with a default rather than testing whether the key is present.
Items that finished with an error so far. Item errors do not fail the batch — it still completes, and every item keeps its own entry in the results file. Omitted from the poll response while zero.
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
The error code, as specified by gRPC status codes.
Set when the batch succeeded: a SynthesizeSpeechBatchResponse naming the results file.
Show child attributes
Type of the serialized message, always type.googleapis.com/ai.inworld.tts.v1.SynthesizeSpeechBatchResponse.
Where the results live. Packaged as FILES, the default for results Inworld hosts: a pre-signed download URL for the results file. Packaged as ZIP: a URL for the archive holding that file at resultsPath. For results delivered to your storage, the archive URL is your outputConfig.resultsUri without its signature. For archives Inworld hosts, it is a pre-signed download URL.
Path of the results file inside the archive at resultsUri. Absent when the results are packaged as FILES, where resultsUri is the results file itself.