# Text to speech

POST /v1/audio/speech: parameters, output formats, and language handling.

## Endpoint

```http
POST /v1/audio/speech
```

JSON in, audio bytes out. One request shape covers plain synthesis, streaming, and every output format. The response body is the raw audio in your requested `response_format` (or a chunked stream when `stream: true`).

> Feeding text from an LLM, or holding a conversation? Use the [WebSocket input-streaming API](https://docs.kenpathlabs.com/input-streaming.md) instead of per-request HTTP — one connection, speech that starts before the sentence ends.

## Request parameters

Only `input` is required. Everything else has a serving-tuned default: **omit any parameter you don’t explicitly need** rather than hardcoding a value, so your integration inherits improvements automatically.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `input` | string | `required` | Text to synthesize (max 5,000 chars). Raw graphemes in any supported language; code-switching within one string is fine. No SSML or phonemes. |
| `voice` | string | `-` | Library voice id from [GET /v1/voices](https://docs.kenpathlabs.com/voices.md): an `sv_`-prefixed id, e.g. `sv_enhdbrj5` (Aanya). |
| `model` | string | `svara-1` | Optional. Any value is accepted (OpenAI-SDK compatibility); generation always uses the current Svara model. |
| `response_format` | enum | `wav` | One of `mp3 opus aac flac wav pcm ulaw alaw`. See Output formats below. |
| `sample_rate` | int | `24000` | Output rate in Hz: `8000 16000 22050 24000 32000 44100 48000`. Codec is 24 kHz native; others resampled in-process. |
| `speed` | float | `1.0` | Speaking speed, `0.7`–`1.5`. Pitch is preserved — only the pace changes. Works on streaming responses too. |
| `stream` | bool | `false` | Stream the audio as it’s generated. See [Streaming](https://docs.kenpathlabs.com/streaming.md). |
| `lang` | string | `auto` | Language hint in any form (`hi`, `hin`, `hindi`, `hi-IN`). Enables number/unit normalization. Omit to auto-detect from script. |
| `bitrate_kbps` | int | - | For lossy formats (mp3/opus/aac). Defaults: mp3 128, opus 64, aac 96. |
| `temperature, top_p, top_k, min_p, repetition_penalty, presence_penalty` | float | - | Sampling knobs. Defaults are mode-aware and serving-tuned; leave them unset unless you have a measured reason. |

> Using an OpenAI SDK? The extended fields (`stream`, `lang`, `sample_rate`, sampling knobs) ride in the SDK’s `extra_body` parameter; see [SDKs](https://docs.kenpathlabs.com/sdks.md).

## Output formats

| Parameter | Type | Default | Description |
|---|---|---|---|
| `mp3` | lossy | - | Universal, small. Default 128 kbps. Best for web delivery and storage. |
| `opus` | lossy | - | Efficient at low bitrates; great for real-time voice and WebRTC. |
| `aac` | lossy | - | Apple-ecosystem friendly. |
| `flac` | lossless | - | Archival / further processing without generation loss. |
| `wav` | pcm container | - | Uncompressed, widely readable. The default. |
| `pcm` | raw | - | Headerless 16-bit LE mono at your sample_rate. Lowest-latency streaming: feed straight to an audio sink. |
| `ulaw / alaw` | telephony | - | 8-bit companded for telephony; pair with sample_rate 8000. |

## Languages & normalization

The model covers 80 languages and switches between them mid-sentence. Send `lang` when you know it (any ISO form works) and the server normalizes numbers, dates, currency, and units into spoken form for that language. When you don’t know it, send nothing; the script is auto-detected. Don’t expose a “normalize” toggle in your UI; leave it on and let the server own it. Drive language pickers from `GET /v1/languages`.

## Examples

```bash
curl -X POST https://api.kenpathlabs.com/v1/audio/speech \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice": "sv_r22w7pwe",
    "input": "Your appointment is confirmed for 3 PM tomorrow.",
    "response_format": "ulaw",
    "sample_rate": 8000
  }' --output prompt.ulaw   # voice sv_r22w7pwe = Aarav
```

```bash
curl -X POST https://api.kenpathlabs.com/v1/audio/speech \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice": "sv_enhdbrj5",
    "lang": "hi",
    "input": "आपका बिल ₹1,250 है और 15 अगस्त तक देय है।",
    "response_format": "mp3"
  }' --output bill.mp3   # voice sv_enhdbrj5 = Aanya
```

```python
audio = client.audio.speech.create(
    model="svara-1",
    voice="sv_r22w7pwe",  # Aarav
    input="Your appointment is confirmed for 3 PM tomorrow.",
    response_format="mp3",
    extra_body={"lang": "en"},
)
audio.write_to_file("prompt.mp3")
```