Realtime TTS-2 is live. Built for realtime conversation that feels human. Read the Realtime TTS-2 announcement

TextToSpeech

Synthesize speech (async)

Submit a synthesis job that runs in the background and immediately receive a long-running operation. Poll the operation via the Get operation endpoint until done is true, then download the results from the time-limited signed URLs in its response. The request body is identical to synchronous synthesis. Unlike the synchronous endpoints, a job never returns audio with requested timestamps silently missing: timestampType in a language without alignment support is rejected at submit, and an alignment failure during synthesis fails the operation.

POST/tts/v1/voice:synthesizeAsync

Results document

When the results are packaged as a zip archive, the operation's response names the archive in resultsUri and this JSON document inside it in resultsPath. That is the case for results delivered to your storage with outputConfig.resultsUri, and for hosted results requested with outputConfig.packaging: ZIP. Every path in the document is relative to it, so it resolves against the same archive.

audioPathstring

Path of the synthesized audio, in the format requested via audioConfig.audioEncoding, for example audio.mp3.

timestampsPathstring

Path of the timestamp alignment JSON, for example timestamps.json. Only present when timestampType was set in the request. See Reading the timestamps document for its form.

Authorizations

Authorizationstringrequired

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

application/json

textstringrequired

The text to be synthesized into speech. Maximum input of 100,000 characters. On-Demand accounts are capped at 10,000 characters per job.

voiceIdstring

The ID of the voice to use for synthesizing speech. Set either voiceId or voiceDesign, not both.

audioConfigobject

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

bitRateinteger

Bits per second of the audio. Only for compressed audio formats (MP3, OGG_OPUS). The default is 128,000.

sampleRateHertzinteger

The synthesis sample rate (in hertz) for this audio. Accepts values within the range [8000, 48000]. Supported sample rates are: 8000, 16000, 22050, 24000, 32000, 44100, 48000.

When this is specified, if this is different from the voice's natural sample rate, then the audio will be converted to the desired sample rate (which might result in worse audio quality), unless the specified sample rate is not supported for the encoding chosen, in which case it will fail the request and return an error. The default is 48,000.

speakingRatenumber

Speaking rate/speed, in the range [0.5, 1.5]. The default is 1.0, which is the normal native speed supported by the specific voice. We recommend using values above 0.8 to ensure high quality.

modelIdstringrequired

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

languagestring

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 to BALANCED behavior.
  • 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

instructionstring

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

Speaking-style instruction for this request — for example speak loudly and urgently or sound out of breath. Applies to the whole request. Write it in English, even when text is in another language. An empty string means unset.

You can also change the instruction mid-text with inline [bracket] tags. A tag applies from where it appears until you change it, so it overrides this field from that point on; [reset] removes the instruction for the rest of the text. Prefer one approach or the other rather than combining them.

See Steering for the full guide.

temperaturenumberdefault: 1

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

synthesisContextobject

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. The texts of all previous requests combined must not exceed 2,000 characters.

Show child attributes

previousRequestsobject[]

Previous requests from the same session or conversation, in the order they were synthesized.

Show child attributes

textstring

The text that was synthesized in the previous request.

voiceDesignobject

Preview. Design a voice for this synthesis request without creating or saving a voice. Supported by inworld-tts-2 on unary, server-streaming, async, and batch synthesis. Omit voiceId. Each request or batch item designs its own voice; repeating a description does not guarantee the same voice. See Ad-hoc voice design.

Show child attributes

designPromptstringrequired

A description of the desired voice, such as its accent, pitch, timbre, and delivery. Use 7–1,024 characters; leading and trailing whitespace does not count toward the minimum. This describes the voice; put the words to speak in text.

outputConfigobject

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.

Show child attributes

resultsUristring

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.json beside every artifact it names, by paths relative to it. The response names the archive in resultsUri and the document in resultsPath.
  • FILES: Each artifact as its own pre-signed download URL. Only for results Inworld hosts: FILES together with resultsUri is rejected with INVALID_ARGUMENT.
  • PACKAGING_UNSPECIFIED: ZIP when resultsUri is set, FILES otherwise.

Available options:PACKAGING_UNSPECIFIEDZIPFILES

Response

200 - application/json

namestring

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.

metadataobject

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

doneboolean

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

errorobject

Show child attributes

codeinteger

The error code, as specified by gRPC status codes.

messagestring

A short description of the error.

detailsobject[]

Show child attributes

@typestring

responseobject

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

Show child attributes

@typestring

Type of the serialized message, always type.googleapis.com/ai.inworld.tts.v1.SynthesizeSpeechAsyncResponse.

audioUristring

Pre-signed download URL for the synthesized audio, in the format requested via audioConfig.audioEncoding. Set when the results are packaged as FILES, the default for results Inworld hosts.

timestampsUristring

Pre-signed download URL for the timestamp alignment JSON. Only present when timestampType was set in the request and the results are packaged as FILES. The file is a JSON array of timestamp objects on one timeline from the start of the audio; see Reading the timestamps document.

resultsUristring

The zip archive holding the results, when they are packaged as ZIP. For results delivered to your storage, your outputConfig.resultsUri without its signature; for an archive Inworld hosts, a pre-signed download URL that expires at expireTime.

resultsPathstring

Path of the results document inside the archive at resultsUri. Read the name from here rather than assuming it.

expireTimestring

Time at which the download URLs expire, approximately 7 days after job completion. Absent when the results were delivered to outputConfig.resultsUri, where nothing is left with Inworld to expire.