The text to be synthesized into speech. Maximum input of 4,000 UTF-16 code units (JavaScript text.length) per HTTP streaming request. Exceeding the limit returns INVALID_ARGUMENT (code 3). SDK versions may apply smaller limits or split the input into separate requests. Required without script; omit it when sending a script. For scripts, the limit applies to the sum of the utterance texts.
TextToSpeech
Synthesize speech (stream)
Inworld TTS API reference: stream text-to-speech audio over HTTP as newline-delimited JSON chunks while the audio is generated.
POST
/tts/v1/voice:streamHTTP request and response framing
Send POST https://api.inworld.ai/tts/v1/voice:stream with
Authorization: Basic <INWORLD_API_KEY> and Content-Type: application/json.
Use the Portal's Base64 credentials unchanged, without encoding them again.
Keep the key on your server; see Authentication for
browser and mobile token options.
curl --no-buffer 'https://api.inworld.ai/tts/v1/voice:stream' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"text": "Hello, world!",
"voiceId": "Ashley",
"modelId": "inworld-tts-2",
"audioConfig": { "audioEncoding": "PCM", "sampleRateHertz": 48000 }
}'The JSON response is newline-delimited JSON (NDJSON): one JSON object per
line, not SSE (data: events) or a single JSON document. Each successful
message wraps its payload in result. Audio is Base64-encoded inside
result.audioContent, not raw audio in the HTTP body. Example lines below use
placeholders for the audio bytes:
{"result":{"audioContent":"<base64-audio>","usage":{"processedCharactersCount":13,"modelId":"inworld-tts-2"}}}
{"result":{"audioContent":"<base64-audio>","usage":{"processedCharactersCount":0,"modelId":"inworld-tts-2"}}}A network read may contain part of a line or several lines. Buffer until a
newline, parse each complete object, and Base64-decode its audio independently.
Do not call response.json() on the whole streaming response or concatenate
Base64 strings before decoding. Process a final non-empty line at EOF too.
Timestamp-only messages can arrive after the audio; keep reading until EOF.
| Request field | Meaning |
|---|---|
text | Up to 4,000 UTF-16 code units per HTTP streaming request |
voiceId | Use the exact voiceId from List voices, such as Ashley |
modelId | Set explicitly; choose from Models, for example inworld-tts-2 |
audioConfig.audioEncoding | Encoding of the decoded audio bytes; see the table below |
audioConfig.sampleRateHertz | Requested output sample rate in Hz; configure your PCM player to match |
The non-streaming endpoint
accepts 2,000 UTF-16 code units, while this endpoint accepts 4,000. In
JavaScript, text.length measures this unit; some emoji count as two. An
oversized request returns INVALID_ARGUMENT (code 3) with a message such as
text length should not exceed 4000 characters. SDK versions can enforce their
own smaller limits or split text into multiple requests. Set modelId explicitly
and consult the documentation for the installed SDK version instead of relying
on its default model or chunk size.
Choose an audio encoding
The table below compares common streaming choices; it is not the full encoding
list. The API also exposes OGG_OPUS, ALAW, MULAW, and FLAC. See the
audioConfig.audioEncoding API reference
for the complete enum and format descriptions.
| Encoding | Decoded bytes in an HTTP stream |
|---|---|
PCM | Raw signed 16-bit little-endian samples, with no WAV header; suitable for a PCM playback queue |
LINEAR16 | A complete WAV header in every audio chunk; do not feed the headers to a raw PCM player or concatenate chunks as one ordinary WAV file |
WAV | A streaming WAV header in the first audio chunk only |
MP3 | Compressed audio; use an MP3-capable streaming decoder/player |
The encoding names describe the audio after Base64 decoding. PCM and
LINEAR16 contain the same sample format but have different framing.
Read the stream in Node.js
This server-side example uses Node.js 20+ built-in fetch. onAudio receives
decoded PCM bytes; enqueue them for playback or write them to a raw PCM file.
A raw PCM file needs its sample rate and channel count supplied to the player.
async function streamSpeech(text, onAudio, { signal } = {}) {
const response = await fetch('https://api.inworld.ai/tts/v1/voice:stream', {
method: 'POST',
headers: {
Authorization: `Basic ${process.env.INWORLD_API_KEY}`,
'Content-Type': 'application/json',
Accept: 'application/json',
},
body: JSON.stringify({
text,
voiceId: 'Ashley',
modelId: 'inworld-tts-2',
audioConfig: { audioEncoding: 'PCM', sampleRateHertz: 48000 },
}),
signal,
});
if (!response.ok) {
const body = await response.text();
let message = body;
try {
const payload = JSON.parse(body);
message = (payload.error ?? payload).message ?? body;
} catch { /* An intermediary may return a non-JSON error. */ }
throw new Error(`HTTP ${response.status}: ${message}`);
}
if (!response.body) throw new Error('Missing response stream');
const decoder = new TextDecoder();
let pending = '';
let processedCharacters = 0;
async function consume(line) {
if (!line.trim()) return;
const message = JSON.parse(line);
if (message.error) throw new Error(message.error.message ?? 'Synthesis failed');
const result = message.result;
processedCharacters += result?.usage?.processedCharactersCount ?? 0;
if (result?.audioContent) {
await onAudio(Buffer.from(result.audioContent, 'base64'));
}
}
for await (const bytes of response.body) {
pending += decoder.decode(bytes, { stream: true });
let newline;
while ((newline = pending.indexOf('\n')) !== -1) {
const line = pending.slice(0, newline);
pending = pending.slice(newline + 1);
await consume(line);
}
}
pending += decoder.decode();
await consume(pending);
return { processedCharacters };
}Errors, usage, and cancellation
Check both the initial HTTP status and each parsed message. A stream can return
an HTTP 200 and later end with an error message:
{"error":{"code":3,"message":"Invalid request"}}Non-streaming endpoints can instead return {"code":5,"message":"Voice not found"}.
For shared error handling, inspect payload.error ?? payload. Codes in these
objects are gRPC status codes, not HTTP status numbers. Preserve any audio
already delivered as partial output and report the failure; a successful HTTP
status alone does not establish that synthesis finished.
For HTTP streaming, usage.processedCharactersCount carries the full input's
UTF-16 length on the first response message; subsequent messages report zero.
Sum this field across messages, or retain the first value. Reading only the last
message reports zero and loses the request's usage.
Pass an AbortController signal to streamSpeech and call abort() to cancel
the fetch and response reader. Handle the rejection as cancellation, and stop
and clear your playback queue separately. Cancellation does not refund text
already metered: the full submitted text is metered when the first response is
emitted, rather than in proportion to the audio you play. Aborting before you
receive audio is not proof that the server has not already metered the request.
Audio chunk size, arrival spacing, and time to first audio vary with text, model,
encoding, and load. Buffer for continuous playback rather than assuming fixed
chunk durations or an arrival rate equal to playback speed. For mono PCM16,
durationSeconds = decodedByteLength / (2 * sampleRateHertz); at 48 kHz,
9,600 decoded bytes represent 100 ms of audio. These are sizing calculations,
not latency guarantees.
Using saved pronunciations? See the pronunciation dictionaries guide.
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
timestampTransportStrategyenum<string>default: "TIMESTAMP_TRANSPORT_STRATEGY_UNSPECIFIED"
How word and character timestamps are delivered. We recommend setting it explicitly rather than relying on the default.
ASYNC: Timestamps can arrive in a trailing message after their audio. The lowest-latency option.SYNC: Timestamps arrive in the same message as their audio. Each message waits until its whole words are aligned, which adds latency.TIMESTAMP_TRANSPORT_STRATEGY_UNSPECIFIED:ASYNCwhenlipsyncConfigis set, since lip-sync implies a real-time experience; otherwiseSYNC. The default is expected to move toASYNC.
Visemes in lipsyncAlignment always arrive with their audio, whichever strategy is used.
Available options:TIMESTAMP_TRANSPORT_STRATEGY_UNSPECIFIEDSYNCASYNC
A chunk containing audio in the requested format. PCM chunks are raw and headerless. LINEAR16 chunks each contain a complete WAV header. For WAV, only the first chunk contains the header.
Show child attributes
Base64-encoded audio bytes in the requested encoding. PCM is headerless signed 16-bit little-endian audio. LINEAR16 includes a WAV header in the non-streaming response and in every HTTP streaming audio chunk; WAV includes a header only in the first streaming audio chunk. Decode each audioContent value separately before playback or concatenation.
Maximum output audio size of 16MB. To avoid errors with longer texts, please use a compressed audio format with an appropriate bit rate, or use the streaming endpoint.
Usage information for the request.
Show child attributes
processedCharactersCountinteger
Number of input UTF-16 code units processed. For HTTP streaming, the first response message carries the full count and subsequent messages report zero. Sum across messages rather than reading only the last message. Cancelling after the request is metered does not reduce the count to the audio played.
Timestamp alignment information (present when alignment or lip-sync is enabled).
Show child attributes
Word-level alignment when timestampType is WORD.
Show child attributes
Detailed phoneme-level timing and viseme information, useful for precise lip-sync animation.
Show child attributes
Array of phonemes that make up this word.
Show child attributes
Character-level alignment when timestampType is CHARACTER.
Show child attributes
Viseme spans for lip-sync, present when the request set lipsyncConfig. If lip-sync is temporarily unavailable, synthesis still succeeds without this field, so check for it rather than assuming it is present. The spans tile the audio with no gaps, and adjacent identical visemes are merged. In streaming responses, every message that carries audio includes the spans for that audio. A span that continues across two messages is split at the boundary. Times are measured from the start of the stream.
The steering instruction Reasoning wrote and applied to this request. Absent when Reasoning didn't run or wrote no instruction. On Synthesize speech (streaming), set on the first message only. To keep the same delivery on a later request, put it in brackets at the start of the text and leave synthesisContext.reasoning unset.
Present only for PER_UTTERANCE. Unary responses contain complete utterance recordings; HTTP streaming responses contain the index of the current utterance. Combined output uses the existing top-level audio fields.
Show child attributes
Complete utterance outputs in script order. Unary only; not populated in HTTP streaming.
Show child attributes
Base64-encoded complete recording, with its own container headers according to audioConfig.
Alignment when requested and available. Times start at zero for this utterance’s audio.
Show child attributes
Word-level alignment when timestampType is WORD.
Show child attributes
Detailed phoneme-level timing and viseme information, useful for precise lip-sync animation.
Show child attributes
Array of phonemes that make up this word.
Show child attributes
Character-level alignment when timestampType is CHARACTER.
Show child attributes
Viseme spans for lip-sync, present when the request set lipsyncConfig. If lip-sync is temporarily unavailable, synthesis still succeeds without this field, so check for it rather than assuming it is present. The spans tile the audio with no gaps, and adjacent identical visemes are merged. In streaming responses, every message that carries audio includes the spans for that audio. A span that continues across two messages is split at the boundary. Times are measured from the start of the stream.
A response may contain an error object if an error happens in the stream.
Show child attributes
The error code, as specified by gRPC status codes