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

---
title: HTTP Streaming
description: Stream audio bytes over a single HTTP response.
---

# HTTP Streaming

`POST /v1/tts/stream` synthesizes the full input text and streams the
audio bytes back as they are generated, over one HTTP response. This lowers
time-to-first-byte compared to waiting for the complete file.

The request body is identical to [`POST /v1/tts/generate`](/api-reference/speech).
Authentication, rate limits, credits, voice/language, and `model_id` are all
validated before streaming starts.

> **Note:**
> `pcm` is the recommended `output_format` for streaming since it has no container
> overhead and is ready for custom playback pipelines.

## Response

The response body is `application/octet-stream`. Usage metadata is returned in
headers:

```text
X-RateLimit-Limit:        15
X-RateLimit-Remaining:    13
X-RateLimit-Reset:        1715678460
X-Characters-Used:        12
X-Audio-Duration-Seconds: 1.8
```

## Streaming to a file

#### Python

```python
with open("speech.pcm", "wb") as file:
    for chunk in client.tts.stream(
        text="வணக்கம், நான் வாக்யம் AI பேசுகிறேன்.",
        model_id="raaga-v1",
        voice="Archana",
        language="ta-IN",
        output_format="pcm",
    ):
        file.write(chunk)
```



#### JavaScript

```ts
import { createWriteStream } from "node:fs";
import { VakyamAIAsync } from "@vakyam-ai/tts";

const client = new VakyamAIAsync({ apiKey: process.env.VAKYAM_API_KEY! });
const output = createWriteStream("speech.pcm");

for await (const chunk of client.tts.stream({
  text: "வணக்கம், நான் வாக்யம் AI பேசுகிறேன்.",
  model_id: "raaga-v1",
  voice: "Archana",
  language: "ta-IN",
  output_format: "pcm",
})) {
  output.write(chunk); // chunk is Uint8Array
}

output.end();
```



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

## Collecting the full stream with metadata (Python)

If you want the complete audio plus the response metadata in one call, the
Python SDK offers `stream_to_bytes`:

#### Python

```python
streamed = client.tts.stream_to_bytes(
    text="வணக்கம்.",
    model_id="raaga-v1",
    voice="Archana",
    language="ta-IN",
)

streamed.save("speech.pcm")
print(streamed.metadata.characters_used)
print(streamed.metadata.duration_seconds)
```

## When to use streaming vs. realtime

* **HTTP streaming** is best when you have the full text up front and want the
  audio to start playing sooner.
* **WebSocket** is best when you produce text sentence-by-sentence (for example
  from an LLM) and want each sentence synthesized as it arrives. See the
  [realtime guide](/guides/realtime-websocket).

---

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