--- title: "Synthesize speech" method: POST path: "/tts/v1/voice" tags: ["TextToSpeech"] --- # Synthesize speech `POST /tts/v1/voice` Receive results after all text input has been processed. ## Request body - Ttsv1SynthesizeSpeechRequest - `text` string, required — The text to be synthesized into speech. Maximum input of 2,000 characters. - `voiceId` string, required — The ID of the voice to use for synthesizing speech. - `audioConfig` Ttsv1AudioConfig — Configurations to use when synthesizing speech. - `audioEncoding` 'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'ALAW' | 'MULAW' | 'FLAC' | 'PCM' | 'WAV' — 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. - `bitRate` integer — Bits per second of the audio. Only for compressed audio formats (`MP3`, `OGG_OPUS`). The default is 128,000. - `sampleRateHertz` integer — 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. - `speakingRate` number, double — 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. - `modelId` string, required — The ID of the model to use for synthesizing speech. See [Models](../../../tts/tts-models) for available models. - `language` string — 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](../../../tts/capabilities/multilingual) for more details. - `deliveryMode` 'DELIVERY_MODE_UNSPECIFIED' | 'STABLE' | 'BALANCED' | 'CREATIVE' — *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. - `temperature` number, float — *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. - `timestampType` 'TIMESTAMP_TYPE_UNSPECIFIED' | 'WORD' | 'CHARACTER' — 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). - TIMESTAMP_TYPE_UNSPECIFIED: 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. - `applyTextNormalization` 'APPLY_TEXT_NORMALIZATION_UNSPECIFIED' | 'ON' | 'OFF' — 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. - `enhanceGeneration` boolean — 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). - `synthesisContext` Ttsv1SynthesisContext — 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. - `previousRequests` object[] — Previous requests from the same session or conversation, in the order they were synthesized. - `text` string — The text that was synthesized in the previous request. ## Response `200` A successful response. - Ttsv1SynthesizeSpeechResponse - `audioContent` string, byte — The audio data bytes encoded in the format as specified in the request. For encodings that are wrapped in containers (e.g. MP3, OPUS) the header is included. For PCM audio a WAV header is included. 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` object — Usage information for the request. - `processedCharactersCount` integer — Number of characters of the input text processed. - `modelId` string — The model used for speech synthesis. - `timestampInfo` object — Timestamp alignment information (present when alignment is enabled). - `wordAlignment` object — Word-level alignment when timestampType is WORD. - `words` string[] — Aligned words in order. - `wordStartTimeSeconds` number[] — Start time for each word in seconds from the beginning of the audio. - `wordEndTimeSeconds` number[] — End time for each word in seconds from the beginning of the audio. - `phoneticDetails` object[] — Detailed phoneme-level timing and viseme information. **Only available for TTS 1.5 and TTS-2 models** (`inworld-tts-1.5-mini`, `inworld-tts-1.5-max`, `inworld-tts-2`). Useful for precise lip-sync animation. - `wordIndex` integer — Index of the word this phonetic detail belongs to (0-based). - `phones` object[] — Array of phonemes that make up this word. - `phoneSymbol` string — The phoneme symbol (IPA notation). - `startTimeSeconds` number — Start time of the phoneme in seconds. - `durationSeconds` number — Duration of the phoneme in seconds. - `visemeSymbol` string — The viseme symbol for lip-sync animation (e.g., `aei`, `o`, `bmp`, `fv`, `l`, `r`, `th`, `qw`, `ee`, `chjsh`, `cdgknstxyz`). - `isPartial` boolean — 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`. - `characterAlignment` object — Character-level alignment when timestampType is CHARACTER. - `characters` string[] — Aligned characters (including punctuation and spaces) in order. - `characterStartTimeSeconds` number[] — Start time for each character in seconds from the beginning of the audio. - `characterEndTimeSeconds` number[] — End time for each character in seconds from the beginning of the audio. ## Other responses - `4XX` — An unexpected error response. --- [API](https://skmtc.net/inworld/apis/inworld-text-to-speech-api.md) · [All operations](https://skmtc.net/inworld/apis/inworld-text-to-speech-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/inworld/inworld-text-to-speech-api/versions/e79009799a0d/schema)