# Озвучить текст

Текст до 1000 знаков → звук одним запросом, без очереди глав.

`POST /tts` · озвучка

Для реплики бота, подписи, уведомления. Ответ обычно за 1–10 секунд. Числа, даты и сокращения прочтутся словами;
ударение можно подсказать знаком `+` перед гласной: `з+амок`. Длиннее 1000 знаков — [книгой](/developers/books-create):
длинный текст читается ровнее и с паузами.

Тот же текст тем же голосом второй раз — бесплатно и мгновенно.

## Тело запроса

JSON, заголовок `content-type: application/json`.

| Поле | Тип | Обязательно | Что это |
|---|---|---|---|
| `text` | строка | да | Текст, до 1000 знаков |
| `voice_id` | строка | да | Голос из `GET /voices` |
| `emotion` | строка | нет | `Нейтрально` (по умолчанию) или другая — если голос умеет играть эмоции |
| `speed` | число | нет | Темп от 0,6 до 1,4 |
| `output` | строка | нет | `audio` (по умолчанию) — сам звук WAV; `url` — JSON со ссылкой |

## Что в ответе

| Поле | Что это |
|---|---|
| тело | Звук WAV (`content-type: audio/wav`) — при `output: audio` |
| `audio_url` | Ссылка на звук — при `output: url` |
| `generated` | `false` — звук был готов, не списан |
| `expires_s` | Сколько секунд живёт ссылка |

## Ошибки

| Код | Когда |
|---|---|
| `402` | Не хватает знаков |
| `409` | Голос сейчас не работает |
| `503` | Озвучка не ответила вовремя — повторите |

```bash
curl -X POST "https://golosar-kniga.tech/api/v1/tts" \
  -H "x-api-key: $KEY" \
  -H "content-type: application/json" \
  -d '{"text": "Здравствуйте! Ваш заказ готов.", "voice_id": "01a134c9-6206-79f0-b812-4f2c0a9d5302"}' \
  -o hello.wav
```

```python
import os, requests

API = "https://golosar-kniga.tech/api/v1"
H = {"x-api-key": os.environ["GOLOSAR_KEY"]}

r = requests.post(f"{API}/tts", headers=H, json={"text": "Здравствуйте! Ваш заказ готов.", "voice_id": "01a134c9-6206-79f0-b812-4f2c0a9d5302"})
r.raise_for_status()
open("hello.wav", "wb").write(r.content)
```

```javascript
import { writeFile } from "node:fs/promises";
const API = "https://golosar-kniga.tech/api/v1";
const H = { "x-api-key": process.env.GOLOSAR_KEY, "content-type": "application/json" };

const r = await fetch(`${API}/tts`, { method: "POST", headers: H, body: JSON.stringify({"text": "Здравствуйте! Ваш заказ готов.", "voice_id": "01a134c9-6206-79f0-b812-4f2c0a9d5302"}) });
if (!r.ok) throw new Error(await r.text());
await writeFile("hello.wav", Buffer.from(await r.arrayBuffer()));
```

```json Ответ 200 при output: url
{
  "audio_url": "https://golosar-kniga.tech/files/eyJrIjoi…",
  "prepared": "До́брый ве́чер! Э́то прове́рка голоса.",
  "generated": false,
  "duration_s": 2.9,
  "expires_s": 3600
}
```