# Синтез речи

`POST /v1/audio/speech` — текст в звук, как `audio.speech` SDK OpenAI. Тело ответа — байты
звука (`audio/mpeg` или `audio/wav` — формат запроса или родной формат модели), id задачи — в заголовке
`X-Job-Id`. Поля — схема `SpeechRequest`.

```bash tab="cURL"
curl https://api.souz.ai/v1/audio/speech \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-audio-3.0-tts-plus", "input": "Добро пожаловать!", "voice": "longanlingxin"}' \
  --output welcome.mp3
```

```python tab="Python"
speech = client.audio.speech.create(model="qwen-audio-3.0-tts-plus", input="Добро пожаловать!", voice="longanlingxin")
speech.write_to_file("welcome.mp3")
```

## Скорость и поток

`speed` (0,25–4) принимается и на результат не влияет: темп — как у модели. Его задают
словами в `instructions`, если модель их принимает. `stream_format: "sse"` — звук
событиями `text/event-stream`: `speech.audio.delta` с base64 звука, затем
`speech.audio.done`.

## Объект задачи вместо байтов

С заголовком `Accept: application/json` ответ — объект задачи: звук — `data[0]`
(`type: "audio"`), в `usage` — `characters`, `seconds` и, у моделей с посимвольной оплатой,
`billed_characters`.

## Голоса и пределы

Голоса, предел текста и формат звука — в карточке модели. Голос или формат, которых у
модели нет, — `400 capability_mismatch` со списком допустимых; если карточка не предлагает
голос, поле `voice` не присылайте. У моделей с посекундной ценой оплачивается длительность
готового звука: ставка — `pricing.amount_micro`, предел — `limits.max_output_seconds`.

## Манера речи и диалог

Если в карточке модели есть поле `instructions`, в нём словами задают, как говорить: тон,
темп и эмоцию («спокойно и тепло», «быстро, с азартом»). Если есть `dialogue` —
вместо `input` присылают реплики по порядку, у каждой свой голос:

```bash tab="cURL"
curl https://api.souz.ai/v1/audio/speech \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-flash-tts-preview",
       "instructions": "Спокойный вечерний разговор, говорят негромко.",
       "dialogue": [{"voice": "Kore", "text": "Ты готов?"},
                    {"voice": "Charon", "text": "Почти. Дай мне минуту."}]}' \
  --output dialogue.wav
```

`input` и `dialogue` вместе — `400 invalid_request` (`mutually_exclusive`). Число разных
голосов, реплик и общий предел текста реплик — в карточке модели; поле, которого у модели
нет, — `400 capability_mismatch`. Эти поля умеют не все каналы модели: запрос с ними идёт
только по тем, что умеют; какие это каналы — превью с `speech_instructions` и
`speech_dialogue`. Указания не тарифицируются: оплачивается озвученный текст.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.