# API reference

> Every HTTP endpoint with its fields and responses, from the API's OpenAPI document.

## Speech

A text in, its audio out. The guide is [The HTTP API](https://docs.vaakini.com/http.md).

### POST `/v1/audio/speech` Create speech

POST https://api.vaakini.com/v1/audio/speech

Synthesizes `input` and streams the audio back as it is made. The input is split into sentences and each is synthesized in turn, so the first audio arrives after the first sentence. The status is sent with the first audio, so an error after audio has started can only abort the body: the response ends without its final chunk, which HTTP clients raise as an error. Treat it as a failed request.

#### Request body

- `model` "vaakini-tts-1" Required
- `input` string, min length 1, max length 20000 Required: The text to speak.
- `voice` string, min length 1 Required: A voice `GET /v1/voices` lists: a built-in voice's name, in any case (e.g. `Monika`), or one of your org's custom voices (`cv_…`).
- `language` "as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te" | null: The text's language. Left out or null: the model picks it from the text's script.
- `response_format` "mp3" | "pcm" | "wav": `mp3`, `pcm` (16-bit little-endian mono) or `wav`.
- `sample_rate` 24000
- `stream_format` "audio"
- `normalize` boolean | null: Speak numbers, currency, dates, times, OTPs, phone numbers, URLs and emails as words in the request's language. Left out or null: the model's default (on).
- `temperature` number | null, ≥ 0.1, ≤ 1.5: Sampling temperature: lower is steadier, higher is more varied. Left out or null: the model's default.
- `top_k` integer | null, ≥ 1, ≤ 2048: Sample from the k likeliest codes. Left out or null: the model's default.
- `top_p` number | null, ≤ 1: Nucleus sampling, above 0 and at most 1. Left out or null: the model's default.
- `repetition_penalty` number | null, ≥ 0, ≤ 5: Penalty on recently repeated codes. Left out or null: the model's default.

**Example**

```json
{
  "model": "vaakini-tts-1",
  "input": "नमस्ते, आप कैसे हैं?",
  "voice": "Monika",
  "language": "hi",
  "response_format": "mp3"
}
```

#### Responses

- 200 The audio, streamed.
- 400 Invalid request (\`bad_request\`)
- 401 Missing or invalid API key (\`unauthorized\`)
- 402 The org is out of credit (\`insufficient_credits\`): buy credit in the dashboard
- 429 The model is at capacity (\`rate_limited\`): try again
- 500 The request failed on our side (\`internal\`)
- 502 The model is unavailable (\`unavailable\`): try again
- 504 The model sent no audio in time (\`timeout\`): try again

## Voices and models

What `voice` and `model` take. The guide is [Voices and languages](https://docs.vaakini.com/voices.md).

### GET `/v1/voices` List voices

GET https://api.vaakini.com/v1/voices

The voices your org can speak with: the built-in voices, then your org's custom voices. Takes no query parameters.

#### Responses

- 200 Successful Response

  - `voices` Voice\[\] Required
- 400 A query parameter was sent (\`bad_request\`)
- 401 Missing or invalid API key (\`unauthorized\`)
- 402 The org is out of credit (\`insufficient_credits\`)

### GET `/v1/models` List models

GET https://api.vaakini.com/v1/models

The model, with its built-in voices, languages, formats, sample rates and options. Needs no API key.

#### Responses

- 200 Successful Response

  - `models` Model\[\] Required

## Custom voices

Your org’s own voices, enabled per org on request. The guide is [Custom voices](https://docs.vaakini.com/custom-voices.md).

### GET `/v1/custom-voices` List your custom voices

GET https://api.vaakini.com/v1/custom-voices

Your org's custom voices, oldest first, whether they're enabled for it, and how many it can hold.

#### Responses

- 200 Successful Response

  - `enabled` boolean Required: Whether custom voices are enabled for your org. Until they are, creating one is refused (`custom_voices_not_enabled`); write to hello@vaakini.com to get them enabled.
  - `limit` integer Required: How many custom voices your org can hold.
  - `voices` CustomVoice\[\] Required
- 401 Missing or invalid API key (\`unauthorized\`)

### POST `/v1/custom-voices` Create a custom voice

POST https://api.vaakini.com/v1/custom-voices

Creates a custom voice from one reference recording. Your org alone can speak it, with its `id` as `voice`, a few seconds after this returns: until then a request that names it is refused as an unknown voice. Creating and keeping voices is free; speaking one costs what any voice costs.

#### Responses

- 201 Created: ready to speak

  - `id` string Required: What `voice` takes on `/v1/stream`, `/v1/audio/speech`, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it.
  - `name` string, min length 1, max length 100 Required
  - `gender` "female" | "male" | null Required: Your label for the voice, shown in `GET /v1/voices`; null when you set none. It doesn't change how the voice sounds.
  - `language` "as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te" Required: The recording's language. The voice speaks every language the model does.
  - `models` CustomVoiceModel\[\] Required
  - `revision` integer, ≥ 1 Required: Which recording the voice speaks: 1 when created, one more each time its recording is replaced (`PUT /v1/custom-voices/{voice_id}/recording`).
  - `created_at` string (date-time) Required

  **Example**

  ```json
  {
    "id": "cv_t76u7a3um3xayk4b",
    "name": "Priya (support)",
    "gender": "female",
    "language": "hi",
    "models": [
      {
        "model": "vaakini-tts-1",
        "mode": "icl_spk"
      }
    ],
    "revision": 1,
    "created_at": "2026-11-10T01:52:33Z"
  }
  ```
- 401 Missing or invalid API key (\`unauthorized\`)
- 403 Custom voices aren't enabled for your org (\`custom_voices_not_enabled\`)
- 409 Your org holds as many custom voices as it can (\`custom_voice_limit\`)
- 422 The request failed validation, or the recording couldn't be used (\`bad_request\`, naming the field)
- 503 The model or the voice store is unavailable (\`unavailable\`); nothing was kept, try again

### GET `/v1/custom-voices/{voice_id}` Get a custom voice

GET https://api.vaakini.com/v1/custom-voices/{voice_id}

#### Parameters

- `voice_id` path, string Required

#### Responses

- 200 Successful Response

  - `id` string Required: What `voice` takes on `/v1/stream`, `/v1/audio/speech`, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it.
  - `name` string, min length 1, max length 100 Required
  - `gender` "female" | "male" | null Required: Your label for the voice, shown in `GET /v1/voices`; null when you set none. It doesn't change how the voice sounds.
  - `language` "as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te" Required: The recording's language. The voice speaks every language the model does.
  - `models` CustomVoiceModel\[\] Required
  - `revision` integer, ≥ 1 Required: Which recording the voice speaks: 1 when created, one more each time its recording is replaced (`PUT /v1/custom-voices/{voice_id}/recording`).
  - `created_at` string (date-time) Required

  **Example**

  ```json
  {
    "id": "cv_t76u7a3um3xayk4b",
    "name": "Priya (support)",
    "gender": "female",
    "language": "hi",
    "models": [
      {
        "model": "vaakini-tts-1",
        "mode": "icl_spk"
      }
    ],
    "revision": 1,
    "created_at": "2026-11-10T01:52:33Z"
  }
  ```
- 401 Missing or invalid API key (\`unauthorized\`)
- 403 Custom voices aren't enabled for your org (\`custom_voices_not_enabled\`)
- 404 No such custom voice in your org

### PATCH `/v1/custom-voices/{voice_id}` Update a custom voice

PATCH https://api.vaakini.com/v1/custom-voices/{voice_id}

Only the name and gender change here. A `gender` of null clears it. To change the recording, transcript, language or mode, replace the recording (`PUT …/recording`).

#### Parameters

- `voice_id` path, string Required

#### Request body

- `name` string, min length 1, max length 100
- `gender` "female" | "male" | null: Null clears it.

#### Responses

- 200 Successful Response

  - `id` string Required: What `voice` takes on `/v1/stream`, `/v1/audio/speech`, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it.
  - `name` string, min length 1, max length 100 Required
  - `gender` "female" | "male" | null Required: Your label for the voice, shown in `GET /v1/voices`; null when you set none. It doesn't change how the voice sounds.
  - `language` "as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te" Required: The recording's language. The voice speaks every language the model does.
  - `models` CustomVoiceModel\[\] Required
  - `revision` integer, ≥ 1 Required: Which recording the voice speaks: 1 when created, one more each time its recording is replaced (`PUT /v1/custom-voices/{voice_id}/recording`).
  - `created_at` string (date-time) Required

  **Example**

  ```json
  {
    "id": "cv_t76u7a3um3xayk4b",
    "name": "Priya (support)",
    "gender": "female",
    "language": "hi",
    "models": [
      {
        "model": "vaakini-tts-1",
        "mode": "icl_spk"
      }
    ],
    "revision": 1,
    "created_at": "2026-11-10T01:52:33Z"
  }
  ```
- 401 Missing or invalid API key (\`unauthorized\`)
- 403 Custom voices aren't enabled for your org (\`custom_voices_not_enabled\`)
- 404 No such custom voice in your org
- 422 The request failed validation

### DELETE `/v1/custom-voices/{voice_id}` Delete a custom voice

DELETE https://api.vaakini.com/v1/custom-voices/{voice_id}

Deletes the voice at once: requests naming it are refused from then on, and its recording and transcript are deleted.

#### Parameters

- `voice_id` path, string Required

#### Responses

- 204 Deleted
- 401 Missing or invalid API key (\`unauthorized\`)
- 403 Custom voices aren't enabled for your org (\`custom_voices_not_enabled\`)
- 404 No such custom voice in your org

### PUT `/v1/custom-voices/{voice_id}/recording` Replace a custom voice's recording

PUT https://api.vaakini.com/v1/custom-voices/{voice_id}/recording

Replaces the voice's recording, transcript, language and mode together, under the same `id`: every request from then on speaks the new recording (within a few seconds), and a reply already being spoken finishes in the old one. The voice's `revision` goes up by one. The name and gender don't change. If the new recording can't be used, the voice keeps its old one.

#### Parameters

- `voice_id` path, string Required

#### Responses

- 200 Replaced: the new recording is ready to speak

  - `id` string Required: What `voice` takes on `/v1/stream`, `/v1/audio/speech`, the LiveKit plugin, the Pipecat service and the Python SDK. Only your org can speak it.
  - `name` string, min length 1, max length 100 Required
  - `gender` "female" | "male" | null Required: Your label for the voice, shown in `GET /v1/voices`; null when you set none. It doesn't change how the voice sounds.
  - `language` "as" | "bn" | "en" | "gu" | "hi" | "kn" | "ml" | "mr" | "or" | "pa" | "ta" | "te" Required: The recording's language. The voice speaks every language the model does.
  - `models` CustomVoiceModel\[\] Required
  - `revision` integer, ≥ 1 Required: Which recording the voice speaks: 1 when created, one more each time its recording is replaced (`PUT /v1/custom-voices/{voice_id}/recording`).
  - `created_at` string (date-time) Required

  **Example**

  ```json
  {
    "id": "cv_t76u7a3um3xayk4b",
    "name": "Priya (support)",
    "gender": "female",
    "language": "hi",
    "models": [
      {
        "model": "vaakini-tts-1",
        "mode": "icl_spk"
      }
    ],
    "revision": 1,
    "created_at": "2026-11-10T01:52:33Z"
  }
  ```
- 401 Missing or invalid API key (\`unauthorized\`)
- 403 Custom voices aren't enabled for your org (\`custom_voices_not_enabled\`)
- 404 No such custom voice in your org
- 422 The request failed validation, or the recording couldn't be used (\`bad_request\`, naming the field)
- 503 The model or the voice store is unavailable (\`unavailable\`); the voice keeps its old recording, try again

## OpenAPI document

The whole HTTP API as OpenAPI 3.1, for code generators and API clients. The WebSocket has [its own page](https://docs.vaakini.com/websocket.md).

```shell
curl https://api.vaakini.com/openapi.json
```
