> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: HTTP streaming
api: "POST /v1/tts/stream"
description: Stream audio bytes for the full input text over one HTTP response.
gridGap: 30
---

# Stream speech over HTTP

`POST` `https://api.vakyam.ai/v1/tts/stream`

Streams audio bytes for the full input text as they are generated. The request
body is identical to [POST /v1/tts/generate](/api-reference/speech).
Authentication, rate limits, credits, voice/language, and `model_id` are
validated before streaming starts.

> **Note:**
> **`voice_name` is deprecated** — use the `voice` parameter instead (a preset
> voice name or a `vc_` custom voice ID). See
> [POST /v1/tts/generate](/api-reference/speech) for details.

#### cURL

```bash
curl -N https://api.vakyam.ai/v1/tts/stream \
  -H "Authorization: Bearer $VAKYAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "வணக்கம்.",
    "model_id": "raaga-v1",
    "voice": "Archana",
    "language": "ta-IN",
    "output_format": "pcm"
  }' --output speech.pcm
```



#### Python

```python
with open("speech.pcm", "wb") as f:
    for chunk in client.tts.stream(
        text="வணக்கம்.",
        model_id="raaga-v1",
        voice="Archana",
        language="ta-IN",
        output_format="pcm",
    ):
        f.write(chunk)
```



#### JavaScript

```ts
for await (const chunk of client.tts.stream({
  text: "வணக்கம்.",
  model_id: "raaga-v1",
  voice: "Archana",
  language: "ta-IN",
  output_format: "pcm",
})) {
  // chunk is Uint8Array
}
```



#### 200 Headers

```text
Content-Type: application/octet-stream
X-Characters-Used: 12
X-Audio-Duration-Seconds: 1.8
X-RateLimit-Limit: 15
X-RateLimit-Remaining: 14
```



#### 402 No credits

```json
{
  "error": {
    "status_code": 402,
    "code": "insufficient_credits",
    "message": "Your account has 120 credits remaining but this request requires 250."
  }
}
```



#### 429 Rate limited

```json
{
  "error": {
    "status_code": 429,
    "code": "rate_limit_exceeded",
    "message": "You have exceeded 60 requests per minute. Retry after 23 seconds."
  }
}
```



#### 429 Too many in flight

```json
{
  "error": {
    "status_code": 429,
    "code": "concurrency_limit_exceeded",
    "message": "This account already has 3 synthesis requests in flight, which is the maximum allowed at once. Wait for one to finish before starting another."
  }
}
```

## Authorization

- `Authorization` (string, required) — Bearer token: `Bearer vak_live_<key>`.

## Body

Same as [POST /v1/tts/generate](/api-reference/speech). `pcm` is recommended for
streaming to avoid container overhead.

#### Request body

```json
{
  "text": "வணக்கம்.",
  "model_id": "raaga-v1",
  "voice": "Archana",
  "language": "ta-IN",
  "output_format": "pcm",
  "sample_rate": 24000,
  "speed": 1.0
}
```

- `text` (string, required) — Text to synthesize. Maximum 3000 Unicode characters.

- `model_id` (string, required) — Model identifier. Must be `raaga-v1`.

- `voice` (string, required) — Voice selector. A preset voice name (e.g. `Archana`) or a custom voice ID beginning with `vc_`. A preset voice must form a valid pair with `language`. Send either `voice` or the deprecated `voice_name`, not both.

- `voice_name` (string, deprecated) — **Deprecated** — use `voice` instead. Temporarily accepted for preset voices only.

- `language` (string, required) — BCP 47 language code: `en-IN`, `hi-IN`, `ta-IN`, `te-IN`, `kn-IN`, `mr-IN`, `gu-IN`, or `bn-IN`.

- `output_format` (string, default mp3) — Audio format: `mp3`, `wav`, `pcm`, or `mulaw`. `pcm` is recommended for streaming to avoid container overhead.

- `sample_rate` (integer, default 24000) — Output sample rate in Hz. One of `8000`, `16000`, `24000`, or `48000`.

- `speed` (number, default 1.0) — Playback speed multiplier, `0.5`–`2.0`.

## Response

The response body is a raw `application/octet-stream` of audio bytes. Usage and
rate-limit metadata are returned as headers:

#### Response headers

```text
Content-Type: application/octet-stream
X-Characters-Used: 12
X-Audio-Duration-Seconds: 1.8
```

- `X-Characters-Used` (integer) — Characters consumed for this request.

- `X-Audio-Duration-Seconds` (number) — Duration of the streamed audio in seconds.

---

*Powered by [holocron.so](https://holocron.so)*