> This page is for Voice APIs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# Text-to-Speech (Streamed JSON)

POST https://api.hume.ai/v0/tts/stream/json
Content-Type: application/json

Streams synthesized speech using the specified voice. If no voice is provided, a novel voice will be generated dynamically. Optionally, additional context can be included to influence the speech's style and prosody. 

The response is a stream of JSON objects including audio encoded in base64.

Reference: https://dev.hume.ai/voice/reference/text-to-speech-tts/synthesize-json-streaming

## Authentication

- `X-Hume-Api-Key` header (required) — API Key authentication via header

## Request

### Body (application/json)

This endpoint expects an OctaveBodyArgs.

- `utterances` (list of Utterance, required) — A list of **Utterances** to be converted to speech output. An **Utterance** is a unit of input for [Octave](/docs/text-to-speech-tts/overview), and includes input `text`, an optional `description` to serve as the prompt for how the speech should be delivered, an optional `voice` specification, and additional controls to guide delivery for `speed` and `trailing_silence`.
- `context` (OctaveBodyArgsContext, optional, nullable) — Utterances to use as context for generating consistent speech style and prosody across multiple requests. These will not be converted to speech output.
- `format` (Format, optional, default: {"type":"mp3"}) — Specifies the output audio file format.
- `include_timestamp_types` (list of enum, optional, default: []) — The set of timestamp types to include in the response. Only supported for Octave 2 requests.
  - Allowed values: `word`, `phoneme`
- `num_generations` (integer, optional, default: 1) — Number of audio generations to produce from the input utterances. Using `num_generations` enables faster processing than issuing multiple sequential requests. Additionally, specifying `num_generations` allows prosody continuation across all generations without repeating context, ensuring each generation sounds slightly different while maintaining contextual consistency.
- `split_utterances` (boolean, optional, default: true) — Controls how audio output is segmented in the response. - When **enabled** (`true`), input utterances are automatically split into natural-sounding speech segments. - When **disabled** (`false`), the response maintains a strict one-to-one mapping between input utterances and output snippets. This setting affects how the `snippets` array is structured in the response, which may be important for applications that need to track the relationship between input text and generated audio segments. When setting to `false`, avoid including utterances with long `text`, as this can result in distorted output.
- `strip_headers` (boolean, optional, default: false) — If enabled, the audio for all the chunks of a generation, once concatenated together, will constitute a single audio file. Otherwise, if disabled, each chunk's audio will be its own audio file, each with its own headers (if applicable).
- `temperature` (double, optional, nullable) — Sampling temperature for the speech generation model. Higher values increase variation; lower values increase consistency. **This is an experimental parameter.** It is recommended to use the default values for most use cases. Defaults when omitted: - Octave 1 voice creation (no voice specified): `0.9` - Octave 1 text-to-speech: `0.8` - Octave 2 text-to-speech: `0.75`
- `version` (enum, optional) — Selects the Octave model version used to synthesize speech for this request. If you omit this field, Hume automatically routes the request to the most appropriate model. Setting a specific version ensures stable and repeatable behavior across requests. Use `2` to opt into the latest Octave capabilities. When you specify version `2`, you must also provide a `voice`. Requests that set `version: 2` without a voice will be rejected. For a comparison of Octave versions, see the [Octave versions](/docs/text-to-speech-tts/overview#octave-versions) section in the TTS overview.
  - Allowed values: `1`, `2`
- `instant_mode` (boolean, optional, default: true) — Enables ultra-low latency streaming, significantly reducing the time until the first audio chunk is received. Recommended for real-time applications requiring immediate audio playback. For further details, see our documentation on [instant mode](/docs/text-to-speech-tts/overview#ultra-low-latency-streaming-instant-mode). - A [voice](/reference/text-to-speech-tts/synthesize-json-streaming#request.body.utterances.voice) must be specified when instant mode is enabled. Dynamic voice generation is not supported with this mode. - Instant mode is only supported for streaming endpoints (e.g., [/v0/tts/stream/json](/reference/text-to-speech-tts/synthesize-json-streaming), [/v0/tts/stream/file](/reference/text-to-speech-tts/synthesize-file-streaming)). - Ensure only a single generation is requested ([num_generations](/reference/text-to-speech-tts/synthesize-json-streaming#request.body.num_generations) must be `1` or omitted).

## Response

### 200

Successful Response

- Streaming response of `TtsOutput`.
- `type`: `audio` (SnippetAudioChunk)
  - `audio` (string, required) — The generated audio output chunk in the requested format.
  - `audio_format` (enum, required) — The generated audio output format.
    - Allowed values: `mp3`, `pcm`, `wav`
  - `chunk_index` (integer, required) — The index of the audio chunk in the snippet.
  - `generation_id` (string, required) — The generation ID of the parent snippet that this chunk corresponds to.
  - `is_last_chunk` (boolean, required) — Whether or not this is the last chunk streamed back from the decoder for one input snippet.
  - `request_id` (string, required) — ID of the initiating request.
  - `snippet_id` (string, required) — The ID of the parent snippet that this chunk corresponds to.
  - `text` (string, required) — The text of the parent snippet that this chunk corresponds to.
  - `transcribed_text` (string, required, nullable) — The transcribed text of the generated audio of the parent snippet that this chunk corresponds to. It is only present if `instant_mode` is set to `false`.
  - `utterance_index` (integer, required, nullable) — The index of the utterance in the request that the parent snippet of this chunk corresponds to.
  - `snippet` (Snippet-Output, optional)
- `type`: `timestamp` (OctaveOutputTimestamp)
  - `generation_id` (string, required) — The generation ID of the parent snippet that this chunk corresponds to.
  - `request_id` (string, required) — ID of the initiating request.
  - `snippet_id` (string, required) — The ID of the parent snippet that this chunk corresponds to.
  - `timestamp` (Timestamp, required) — A word or phoneme level timestamp for the generated audio.

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### Utterance

- `text` (string, required) — The input text to be synthesized into speech.
- `description` (string, optional, nullable) — Natural language instructions describing how the synthesized speech should sound, including but not limited to tone, intonation, pacing, and accent. **This field behaves differently depending on whether a voice is specified**: - **Voice specified**: the description will serve as acting directions for delivery. Keep directions concise—100 characters or fewer—for best results. See our guide on [acting instructions](/docs/text-to-speech-tts/acting-instructions). - **Voice not specified**: the description will serve as a voice prompt for generating a voice. See our [prompting guide](/docs/text-to-speech-tts/prompting) for design tips.
- `speed` (double, optional, default: 1) — Speed multiplier for the synthesized speech. Extreme values below 0.75 and above 1.5 may sometimes cause instability to the generated output.
- `trailing_silence` (double, optional, default: 0) — Duration of trailing silence (in seconds) to add to this utterance
- `voice` (VoiceRef, optional, nullable) — The `name` or `id` associated with a **Voice** from the **Voice Library** to be used as the speaker for this and all subsequent `utterances`, until the `voice` field is updated again. See our [voices guide](/docs/text-to-speech-tts/voices) for more details on generating and specifying **Voices**.

### OctaveBodyArgsContext

Utterances to use as context for generating consistent speech style and prosody across multiple requests. These will not be converted to speech output.

### Format

Specifies the output audio file format.

- `type`: `mp3` (Mp3Format)
- `type`: `pcm` (PcmFormat)
- `type`: `wav` (WavFormat)

### Snippet-Output

- `audio` (string, required) — The segmented audio output in the requested format, encoded as a base64 string.
- `generation_id` (string, required) — The generation ID this snippet corresponds to.
- `id` (string, required) — A unique ID associated with this **Snippet**.
- `text` (string, required) — The text for this **Snippet**.
- `timestamps` (list of Timestamp, required) — A list of word or phoneme level timestamps for the generated audio. Timestamps are only returned for Octave 2 requests.
- `transcribed_text` (string, required, nullable) — The transcribed text of the generated audio. It is only present if `instant_mode` is set to `false`.
- `utterance_index` (integer, required, nullable) — The index of the utterance in the request this snippet corresponds to.

### Timestamp

- `text` (string, required) — The word or phoneme text that the timestamp corresponds to.
- `time` (MillisecondInterval, required) — The start and end timestamps for the word or phoneme in milliseconds.
- `type` (enum, required)
  - Allowed values: `word`, `phoneme`

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)

### VoiceRef

### ContextGenerationId

- `generation_id` (string, required) — The ID of a prior TTS generation to use as context for generating consistent speech style and prosody across multiple requests. Including context may increase audio generation times.

### ContextUtterances

- `utterances` (list of Utterance, required)

### MillisecondInterval

- `begin` (integer, required) — Start time of the interval in milliseconds.
- `end` (integer, required) — End time of the interval in milliseconds.

### ValidationErrorLocItems

### VoiceId

- `id` (string, required) — The unique ID associated with the **Voice**.
- `provider` (enum, optional) — Specifies the source provider associated with the chosen voice. - **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library), containing a variety of preset, shared voices. - **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. If no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's **Voice Library**, you must explicitly set the provider to `HUME_AI`. Preset voices from Hume's **Voice Library** are accessible by all users. In contrast, your custom voices are private and accessible only via requests authenticated with your API key.
  - Allowed values: `HUME_AI`, `CUSTOM_VOICE`

### VoiceName

- `name` (string, required) — The name of a **Voice**.
- `provider` (enum, optional) — Specifies the source provider associated with the chosen voice. - **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library), containing a variety of preset, shared voices. - **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. If no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's **Voice Library**, you must explicitly set the provider to `HUME_AI`. Preset voices from Hume's **Voice Library** are accessible by all users. In contrast, your custom voices are private and accessible only via requests authenticated with your API key.
  - Allowed values: `HUME_AI`, `CUSTOM_VOICE`

## Examples

**Request**

```json
{
  "utterances": [
    {
      "text": "Beauty is no quality in things themselves: It exists merely in the mind which contemplates them.",
      "voice": {
        "name": "Male English Actor",
        "provider": "HUME_AI"
      }
    }
  ]
}
```