TextToSpeech
Synthesize speech
Receive results after all text input has been processed.
/tts/v1/voiceRequest and response
Send POST https://api.inworld.ai/tts/v1/voice with
Authorization: Basic <INWORLD_API_KEY> and Content-Type: application/json.
Use the Base64 credentials copied from the Portal without encoding them again.
{
"text": "Hello, world!",
"voiceId": "Ashley",
"modelId": "inworld-tts-2",
"audioConfig": { "audioEncoding": "MP3" }
}text accepts up to 2,000 UTF-16 code units (JavaScript text.length).
Select a modelId from Models and a voiceId from
List voices. Set the model
explicitly; SDK defaults may refer to older models.
The response is a single JSON object with audioContent (Base64-encoded audio),
usage.processedCharactersCount, usage.modelId, and optional timestampInfo.
Unlike HTTP streaming, these fields are not wrapped in result.
{
"audioContent": "<base64-audio>",
"usage": { "processedCharactersCount": 13, "modelId": "inworld-tts-2" }
}For PCM, decoded bytes are headerless PCM16. LINEAR16 includes a WAV header.
For playback before generation completes or text up to 4,000 code units, use
HTTP streaming,
which has a different response format and per-chunk header rules.
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.
textstringrequired
The text to be synthesized into speech. The non-streaming endpoint accepts up to 2,000 UTF-16 code units (JavaScript text.length). The HTTP streaming endpoint accepts up to 4,000; see its text field.
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 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
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.
audioContentstring
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.
usageobject
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.
modelIdstring
The model used for speech synthesis.
timestampInfoobject
Timestamp alignment information (present when alignment is enabled).
Show child attributes
wordAlignmentobject
Word-level alignment when timestampType is WORD.
Show child attributes
wordsstring[]
Aligned words in order.
wordStartTimeSecondsnumber[]
Start time for each word in seconds from the beginning of the audio.
wordEndTimeSecondsnumber[]
End time for each word in seconds from the beginning of the audio.
phoneticDetailsobject[]
Detailed phoneme-level timing and viseme information, useful for precise lip-sync animation.
Show child attributes
wordIndexinteger
Index of the word this phonetic detail belongs to (0-based).
phonesobject[]
Array of phonemes that make up this word.
Show child attributes
phoneSymbolstring
The phoneme symbol (IPA notation).
startTimeSecondsnumber
Start time of the phoneme in seconds.
durationSecondsnumber
Duration of the phoneme in seconds.
visemeSymbolstring
The viseme symbol for lip-sync animation (e.g., aei, o, bmp, fv, l, r, th, qw, ee, chjsh, cdgknstxyz).
isPartialboolean
True when the server considers the word potentially unstable (e.g., last word in a non-final streaming update). Clients may choose to delay processing partial words until isPartial becomes false.
characterAlignmentobject
Character-level alignment when timestampType is CHARACTER.
Show child attributes
charactersstring[]
Aligned characters (including punctuation and spaces) in order.
characterStartTimeSecondsnumber[]
Start time for each character in seconds from the beginning of the audio.
characterEndTimeSecondsnumber[]
End time for each character in seconds from the beginning of the audio.