> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt.
> For full documentation content in one file, see https://docs.sarvam.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# REST Stream

POST https://api.sarvam.ai/text-to-speech/stream
Content-Type: application/json

Converts the input text into a streamed spoken audio response.

This endpoint supports streaming audio using the specified output codec (e.g., `audio/mpeg` for MP3). The response is returned as a binary audio stream, which can be played or saved directly by the client.

Supports the `dict_id` parameter to apply a [pronunciation dictionary](https://docs.sarvam.ai/api-reference-docs/pronunciation-dictionary/create) during synthesis.

Reference: https://docs.sarvam.ai/api-reference/text-to-speech/convert-stream

## Authentication

- `api-subscription-key` header (required) — API Key authentication via header

## Request

### Body (application/json)

This endpoint expects a Sarvam_Model_API_TextToSpeechStreamRequest.

- `text` (string, required) — The text to be converted into streamed speech. **Features:** - Max 3500 characters - Supports code-mixed text (English and Indic languages) **Important Note:** - For numbers larger than 4 digits, use commas (e.g., '10,000' instead of '10000') - This ensures proper pronunciation as a whole number
- `language_code` (enum, optional) — The language code in BCP-47 format.
  - Allowed values: `bn-IN`, `en-IN`, `gu-IN`, `hi-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `od-IN`, `pa-IN`, `ta-IN`, `te-IN`
- `speaker` (enum, optional, nullable) — The speaker voice to be used for the output audio. **Default:** shubh (for bulbul:v3), anushka (for bulbul:v2) **Note:** Speaker selection must match the chosen model version. **Important:** Speaker names are case-sensitive and must be lowercase (e.g., `ritu` not `Ritu`).
  - Allowed values: `anushka`, `abhilash`, `manisha`, `vidya`, `arya`, `karun`, `hitesh`, `aditya`, `ritu`, `priya`, `neha`, `rahul`, `pooja`, `rohan`, `simran`, `kavya`, `amit`, `dev`, `ishita`, `shreya`, `ratan`, `varun`, `manan`, `sumit`, `roopa`, `kabir`, `aayan`, `shubh`, `ashutosh`, `advait`, `anand`, `tanya`, `tarun`, `sunny`, `mani`, `gokul`, `vijay`, `shruti`, `suhani`, `mohit`, `kavitha`, `rehan`, `soham`, `rupali`
- `pitch` (double, optional, nullable) — Controls the pitch of the audio. Range: -0.75 to 0.75. Default is 0.0. **Note:** Only supported for bulbul:v2.
- `pace` (double, optional, nullable, default: 1) — Controls the speed of the audio. Default is 1.0. **Model-specific ranges:** - **bulbul:v3:** 0.5 to 2.0 - **bulbul:v2:** 0.3 to 3.0
- `loudness` (double, optional, nullable) — Controls the loudness of the audio. Range: 0.3 to 3.0. Default is 1.0. **Note:** Only supported for bulbul:v2.
- `speech_sample_rate` (enum, optional, nullable, default: 22050) — Specifies the sample rate of the output audio. Default is 22050 Hz. **Note:** OPUS codec only supports 8000, 12000, 16000, 24000, 48000 Hz.
  - Allowed values: `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000`
- `enable_preprocessing` (boolean, optional, default: false) — Controls whether normalization of English words and numeric entities is performed. Default is false.
- `model` (enum, optional) — Specifies the model to use for text-to-speech conversion. Default is bulbul:v2.
  - Allowed values: `bulbul:v2`, `bulbul:v3`
- `temperature` (double, optional, nullable, default: 0.6) — Controls the randomness of the output. Range: 0.01 to 1.0. Default is 0.6. **Note:** Only supported for bulbul:v3.
- `enable_cached_responses` (boolean, optional, default: false) — Enable caching for the request. Default is false. Currently in beta.
- `dict_id` (string, optional, nullable) — The ID of a pronunciation dictionary to apply during synthesis. When provided, matching words in the input text will be replaced with their custom pronunciations before generating speech. Create and manage dictionaries via the [Pronunciation Dictionary API](https://docs.sarvam.ai/api-reference-docs/pronunciation-dictionary/create). Only supported by **bulbul:v3**.
- `output_audio_codec` (enum, optional) — Specifies the codec for the streamed output audio (e.g., 'mp3').
  - Allowed values: `mp3`, `linear16`, `mulaw`, `alaw`, `opus`, `flac`, `aac`, `wav`
- `output_audio_bitrate` (enum, optional) — Bitrate for the streamed output audio. Default is '128k'.
  - Allowed values: `32k`, `64k`, `96k`, `128k`, `192k`

## Response

### 200

Success. Returns a streamed audio response in the requested format (e.g., `audio/mpeg` for MP3, `audio/wav` for WAV).

- File download.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

### 403 Forbidden Error

Forbidden

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

### 422 Unprocessable Entity Error

Unprocessable Entity

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

### 429 Too Many Requests Error

Quota Exceeded

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

### 500 Internal Server Error

Internal Server Error

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

## Types

### Sarvam_Model_API_ErrorDetails

- `request_id` (string, required, nullable)
- `message` (string, required) — Message describing the error
- `code` (enum, required) — Error code for the specific error that has occurred. Refer to the error code documentation for more details.
  - Allowed values: `invalid_request_error`, `internal_server_error`, `unprocessable_entity_error`, `insufficient_quota_error`, `invalid_api_key_error`, `authentication_error`, `not_found_error`, `rate_limit_exceeded_error`, `model_call_error`, `gateway_timeout_error`, `billing_service_unavailable_error`

## Examples

**Request**

```json
{
  "text": "Welcome to Sarvam AI!"
}
```

**SDK Code**

```typescript
import { SarvamAIClient } from "sarvamai";
import fs from "fs";

const client = new SarvamAIClient({
  apiSubscriptionKey: process.env.SARVAM_API_KEY,
});

const response = await client.textToSpeech.convertStream({
  text: "Welcome to Sarvam AI!",
});

const audio = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("output.mp3", audio);

```

```swift
import Foundation

let url = URL(string: "https://api.sarvam.ai/text-to-speech/stream")!

var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("YOUR_SARVAM_API_KEY", forHTTPHeaderField: "api-subscription-key")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let payload: [String: Any] = [
    "text": "Welcome to Sarvam AI!"
]
request.httpBody = try JSONSerialization.data(withJSONObject: payload)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("Error:", error)
        return
    }
    // The response body is a raw binary audio stream — save it directly.
    if let data = data {
        try? data.write(to: URL(fileURLWithPath: "output.mp3"))
        print("Saved output.mp3 (\(data.count) bytes)")
    }
}
task.resume()

```

```python
import requests

url = "https://api.sarvam.ai/text-to-speech/stream"

payload = { "text": "Welcome to Sarvam AI!" }
headers = {
    "api-subscription-key": "<apiSubscriptionKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sarvam.ai/text-to-speech/stream"

	payload := strings.NewReader("{\n  \"text\": \"Welcome to Sarvam AI!\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-subscription-key", "<apiSubscriptionKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sarvam.ai/text-to-speech/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-subscription-key"] = '<apiSubscriptionKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"Welcome to Sarvam AI!\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sarvam.ai/text-to-speech/stream")
  .header("api-subscription-key", "<apiSubscriptionKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"Welcome to Sarvam AI!\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sarvam.ai/text-to-speech/stream', [
  'body' => '{
  "text": "Welcome to Sarvam AI!"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'api-subscription-key' => '<apiSubscriptionKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sarvam.ai/text-to-speech/stream");
var request = new RestRequest(Method.POST);
request.AddHeader("api-subscription-key", "<apiSubscriptionKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"text\": \"Welcome to Sarvam AI!\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```