---
title: "Synthesize speech from text in a named voice"
method: POST
path: "/v1/tts/{voice_id}"
tags: ["Speech"]
---

# Synthesize speech from text in a named voice

`POST /v1/tts/{voice_id}`

## Request

- Base URL: `https://api.kalpalabs.ai`
- URL: `https://api.kalpalabs.ai/v1/tts/{voice_id}`
- Auth: HTTP bearer

Render the given text as speech (mono WAV, 24 kHz unless `sample_rate` asks for another rate) in one of the named voices from GET /v1/voices.

## Path parameters

- `voice_id` string, required: A named voice id, as listed by GET /v1/voices.

## Request body

- VoiceTtsRequest: Text to speak in a named voice; the voice is the `voice_id` in the path.
  - `text` string, required: Text to speak; must contain at least one non-whitespace character.
  - `model` string, nullable: Public model id (see GET /v1/models). Omit/null for the default model.
  - `params` GenParamsModel: Generation knobs, all optional — the defaults are the tuned production sampling, shared by every generation endpoint (served with UI ranges at GET /v1/info).
    - `temperature` number
    - `acoustic_temperature` number, nullable: Temperature for the voice's fine acoustic detail; null = follow `temperature`.
    - `audio_quality` 'low' | 'medium' | 'high': Playback fidelity: high = full quality (default); lower tiers reduce fidelity, not payload size.
  - `output_format` 'wav': Encoding of `audio.data_b64`: a 16-bit PCM WAV file, mono.
  - `sample_rate` 8000 | 16000 | 22050 | 24000 | 32000 | 44100 | 48000: Output sample rate in Hz.

## Response `200`

Successful Response

- TtsResponse
  - `request_id` string, required: Correlation id; identical to the `X-Request-ID` response header.
  - `model` string, required: Resolved public model id that served the request.
  - `text` string, required: The text that was spoken (echoes the request).
  - `audio` AudioPayload, required
    - `format` string: Container/encoding of `data_b64` (16-bit PCM WAV).
    - `sample_rate` integer, required: Sample rate of the audio in Hz.
    - `audio_quality` 'low' | 'medium' | 'high', required: Fidelity tier this audio was rendered at (high = full quality).
    - `data_b64` string, required: Base64-encoded 16-bit PCM WAV (mono).
  - `usage` Usage, required
    - `input_chars` integer: Characters of input text billed for this request.
    - `input_audio_seconds` number: Seconds of input audio supplied (converse).
    - `output_audio_seconds` number: Seconds of audio generated.
  - `meta` object: Backend-specific diagnostics (latency, frames, …).

## Other responses

- `400`: Semantically invalid request.
- `401`: Missing or invalid API key.
- `402`: Your organization's allowance of generated audio is used up or has expired.
- `403`: The organization is suspended.
- `404`: Unknown voice id, or a voice not offered for the requested model.
- `422`: Request validation failed.
- `429`: Rate limit exceeded.
- `500`: Unexpected internal error.
- `502`: The inference backend failed.
- `503`: Temporarily unavailable: the model is overloaded (`overloaded`; retry after `Retry-After`), or API-key verification is down (`service_unavailable`).

## Changes

- **2026-10-21** `f41853b80be7`: 1 warning
  - removed the request property `params/max_new_tokens`
- **2026-10-21** `88068ba536d2`: 1 breaking, 2 info
  - added the pattern `\S` to the request property `text`
  - added the new optional request property `output_format`
  - added the new optional request property `sample_rate`
- **2026-10-12** `c2e702455f84`: 2 info
  - added the non-success response with the status `402`
  - added the non-success response with the status `403`
- **2026-08-27** `2448428bd895`: 1 warning
  - removed the request property `params/top_k`
- **2026-08-08** `60add3abf640`: 2 warning, 2 info
  - removed the request property `params/penalty_window`
  - removed the request property `params/repetition_penalty`
  - the `max_new_tokens` request property default value `512` was removed
  - request property `params/max_new_tokens` list-of-types was widened by adding types `null` to media type `application/json`

[Operation history](https://skmtc.dev/kalpalabs/apis/kalpa-speech-api/changes/v1/tts/:voice_id/post.md)

---

[API](https://skmtc.dev/kalpalabs/apis/kalpa-speech-api.md) - [All operations](https://skmtc.dev/kalpalabs/apis/kalpa-speech-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kalpalabs/apis/kalpa-speech-api/revisions/e01fbbfe1ef3?raw)