> 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 (Json)

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

Synthesizes one or more input texts into 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 includes the base64-encoded audio and metadata in JSON format.

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

## 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

- `generations` (list of Generation, required)
- `request_id` (string, required, nullable) — A unique ID associated with this request for tracking and troubleshooting. Use this ID when contacting [support](/support) for troubleshooting assistance.

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

### Generation

- `audio` (string, required) — The generated audio output in the requested format, encoded as a base64 string.
- `duration` (double, required) — Duration of the generated audio in seconds.
- `encoding` (Encoding, required) — Encoding information about the generated audio, including the `format` and `sample_rate`.
- `file_size` (integer, required) — Size of the generated audio in bytes.
- `generation_id` (string, required) — A unique ID associated with this TTS generation that can be used as context for generating consistent speech style and prosody across multiple requests.
- `snippets` (list of list of Snippet-Output, required) — A list of snippet groups where each group corresponds to an utterance in the request. Each group contains segmented snippets that represent the original utterance divided into more natural-sounding units optimized for speech delivery.

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

### Encoding

Encoding information about the generated audio, including the `format` and `sample_rate`.

- `format` (enum, required) — Format for the output audio.
  - Allowed values: `mp3`, `pcm`, `wav`
- `sample_rate` (integer, required) — The sample rate (`Hz`) of the generated audio. The default sample rate is `48000 Hz`.

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

### 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`

### 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`

### MillisecondInterval

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

## Examples

**Request**

```json
{
  "utterances": [
    {
      "text": "Beauty is no quality in things themselves: It exists merely in the mind which contemplates them.",
      "description": "Middle-aged masculine voice with a clear, rhythmic Scots lilt, rounded vowels, and a warm, steady tone with an articulate, academic quality."
    }
  ],
  "context": {
    "utterances": [
      {
        "description": "A curious student with a clear and respectful tone, seeking clarification on Hume's ideas with a straightforward question.",
        "text": "How can people see beauty so differently?"
      }
    ]
  },
  "format": {
    "type": "mp3"
  },
  "num_generations": 1
}
```

**Response**

```json
{
  "generations": [
    {
      "audio": "//PExAA0DDYRvkpNfhv3JI5JZ...etc.",
      "duration": 7.44225,
      "encoding": {
        "format": "mp3",
        "sample_rate": 48000
      },
      "file_size": 120192,
      "generation_id": "795c949a-1510-4a80-9646-7d0863b023ab",
      "snippets": [
        [
          {
            "audio": "//PExAA0DDYRvkpNfhv3JI5JZ...etc.",
            "generation_id": "795c949a-1510-4a80-9646-7d0863b023ab",
            "id": "37b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
            "text": "Beauty is no quality in things themselves: It exists merely in the mind which contemplates them.",
            "timestamps": [],
            "utterance_index": 0
          }
        ]
      ]
    }
  ],
  "request_id": "66e01f90-4501-4aa0-bbaf-74f45dc15aa725906"
}
```