# The HTTP API

> POST /v1/audio/speech: send a text, get its audio back as it is spoken. From any language.

## Authentication

Every request carries an API key from the dashboard’s [API keys](https://app.vaakini.com/app/api-keys) page.

```http
Authorization: Bearer vk_…
```

The host is `https://api.vaakini.com`. A missing or wrong key is answered with 401 (`unauthorized`).

## The request

`POST /v1/audio/speech` with a JSON body: the text, a voice and the model.

**MP3**

```shell
curl https://api.vaakini.com/v1/audio/speech \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vaakini-tts-1",
  "voice": "Monika",
  "language": "hi",
  "input": "नमस्ते, आपका ऑर्डर कल पहुँच जाएगा।",
  "response_format": "mp3"
}' \
  --output speech.mp3
```

**PCM, with an option**

```shell
curl https://api.vaakini.com/v1/audio/speech \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vaakini-tts-1",
    "voice": "Monika",
    "language": "hi",
    "input": "नमस्ते, आपका ऑर्डर कल पहुँच जाएगा। डिलीवरी से पहले आपको कॉल आएगा।",
    "response_format": "pcm",
    "temperature": 0.6
  }' \
  --output speech.pcm
```

The text is split into sentences and each is spoken in turn. The request is shaped like OpenAI’s `/v1/audio/speech`, so a client written for that needs a new URL, key, `model` and `voice`.

## Fields

Any other field is refused.

- `model` (`string`, Required): `vaakini-tts-1`.
- `input` (`string`, Required): The text to speak, 1 to 20,000 characters. It can carry [emotion tags](https://docs.vaakini.com/options.md#emotion-tags).
- `voice` (`string`, Required): One of Vaakini’s voices by name, in any case (`Monika`), or the id of one of your org’s [custom voices](https://docs.vaakini.com/custom-voices.md) (`cv_…`). [Voices and languages](https://docs.vaakini.com/voices.md) lists them.
- `language` (`string`, Optional): The language the text is in: `as` , `bn` , `en` , `gu` , `hi` , `kn` , `ml` , `mr` , `or` , `pa` , `ta` or `te`. Left out, the model picks it from the script of each sentence.
- `response_format` (`string`, Default "mp3"): `mp3`, `pcm` or `wav`.
- `sample_rate` (`integer`, Default 24000): 24000 is the only rate.
- `normalize` (`boolean`, Optional; left out or null: on): Speak numbers, currency, dates, times, OTPs, phone numbers, URLs and emails as words in the request’s language. `false` turns it off: the text is spoken as written.
- `temperature` (`number`, Optional; left out or null: the model's default): Sampling temperature, 0.1 to 1.5: lower is steadier, higher is more varied.
- `top_k` (`integer`, Optional; left out or null: the model's default): Sample from the k likeliest codes, 1 to 2048.
- `top_p` (`number`, Optional; left out or null: the model's default): Nucleus sampling, above 0 and at most 1.
- `repetition_penalty` (`number`, Optional; left out or null: the model's default): Penalty on recently repeated codes, 0 to 5.

## The response

The audio, streamed as it is spoken.

| response_format | Content-Type | The audio |
| --- | --- | --- |
| mp3 | audio/mpeg | MP3, 24000 Hz, mono |
| pcm | audio/pcm | 16-bit little-endian PCM, 24000 Hz, mono, no header |
| wav | audio/wav | The same PCM with a WAV header |

The body is chunked: the first audio arrives when the first sentence starts to be spoken, and the response ends when the last one has been. Read it as a stream to play it while it arrives. Because a WAV’s header is sent before its length is known, some players show no duration for it.

## Errors

A JSON body with the error's code, a message and whether trying again can help.

```shell
curl -i https://api.vaakini.com/v1/audio/speech \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "vaakini-tts-1", "voice": "Monika", "input": "नमस्ते।", "speed": 1.2}'
```

```http
HTTP/1.1 400 Bad Request
content-type: application/json

{"error":{"code":"bad_request","message":"invalid request: speed: vaakini-tts-1 takes no speed","retryable":false}}
```

[Errors](https://docs.vaakini.com/errors.md) lists every code and its status.

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 your HTTP client raises as an error (an incomplete or prematurely closed response). Treat that request as failed.

## Voices and the model

Two GETs say what voice and model take.

```shell
curl https://api.vaakini.com/v1/voices \
  -H "Authorization: Bearer $VAAKINI_API_KEY"
```

`GET /v1/voices` lists the voices your org can speak with; [Listing voices](https://docs.vaakini.com/voices.md#list) shows its answer.

```shell
curl https://api.vaakini.com/v1/models
```

`GET /v1/models` needs no key. It answers the model with its voices’ names, languages, formats, sample rates and options. The [API reference](https://docs.vaakini.com/reference.md) has every field of both.
