# Создать озвучку (TTS)

Source: https://provod.ai/ru/docs/audio-speech

`POST /v1/audio/speech` принимает JSON и возвращает байты аудио. Для авторизации передайте `Authorization: Bearer` с API-ключом рабочего пространства.

## Получить MP3

Выберите модель и голос в [каталоге аудио](/ru/docs/audio). ID из примера должны быть доступны в вашем развёртывании. Для команд нужны `curl` и `jq`.

```bash
export PROVOD_API_KEY="sk_..."
export AUDIO_MODEL="speechkit-tts-general"
export AUDIO_VOICE="marina"

jq -n --arg model "$AUDIO_MODEL" --arg voice "$AUDIO_VOICE" '{
  model: $model,
  voice: $voice,
  input: "Hello! This is a short speech sample.",
  response_format: "mp3"
}' | curl --fail-with-body --silent --show-error \
  https://api.provod.ai/v1/audio/speech \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- -D speech.headers -o speech.mp3
```

После успешного HTTP-ответа откройте `speech.mp3`. При HTTP-ошибке файл может содержать её описание, а не аудио. Для MP3 ответ имеет тип `audio/mpeg`. В JavaScript читайте байты, а не `response.json()`:

```javascript
import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.provod.ai/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PROVOD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: process.env.AUDIO_MODEL,
    voice: process.env.AUDIO_VOICE,
    input: "Hello! This is a short speech sample.",
    response_format: "mp3",
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));
```

## Поля запроса

| Поле                                      | Тип                            | Поведение                                                                                                                     |
| ----------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `model`                                   | строка, обязательно            | Точный публичный ID аудиомодели с операцией `speech`                                                                          |
| `input`                                   | строка или массив, обязательно | Непустой текст либо реплики с `text`, необязательными `voice` и `instructions`; массив требует поддержки нескольких говорящих |
| `voice`                                   | строка                         | Публичный ID голоса этой модели; при отсутствии нужен совместимый голос по умолчанию                                          |
| `response_format`                         | `mp3` или `pcm`                | По умолчанию `pcm`; выбирайте опубликованный профиль вывода                                                                   |
| `speed`                                   | положительное число            | Множитель скорости в диапазоне `minSpeed`–`maxSpeed` выбранного профиля                                                       |
| `instructions`                            | строка                         | Пожелания к подаче речи; маршрут без поддержки инструкций может их игнорировать                                               |
| `input_references`                        | массив                         | Референсы в пределах опубликованных ограничений модели                                                                        |
| `provider`, `session_id`, `user`, `trace` | объекты или строки             | [Общие параметры аудио](/ru/docs/audio)                                                                                       |

Проверьте `maxInputCharacters` и `maxInputBytes`. Неизвестные поля и несовместимые сочетания голоса, формата и референсов отклоняются. Инструкции по подаче — исключение: маршрут без их поддержки может создать озвучку, проигнорировав пожелания. Если вам важны заданные тон и эмоции, проверьте `instructions` в возможностях модели.

## Сочетания голоса и формата

Сохраните каталог в `audio-models.json`, задайте `AUDIO_MODEL` и посмотрите проверенные голосовые профили:

```bash
jq --arg model "$AUDIO_MODEL" '
  .data[] | select(.id == $model) | .audio.profiles[]
  | select(.operation == "speech") | .profiles[]
  | {voice, voiceFamily, isDefault, format, sampleRateHz, channels, minSpeed, maxSpeed}
' audio-models.json
```

При смене модели могут измениться ID голосов, диапазон скорости и характеристики аудио. Передавайте точный публичный ID из профиля. Поддерживаемые языки и примеры звучания видны в галерее голосов кабинета.

PCM — это знаковое 16-битное аудио little-endian без WAV-заголовка. Для воспроизведения или упаковки в контейнер читайте `X-Audio-Sample-Rate` и `X-Audio-Channels`; единой частоты 24 кГц для всех моделей нет. Эти заголовки также описывают MP3-ответы. Результат возвращается с `Cache-Control: no-store`.

## Референсы и несколько говорящих

Модели с `multiSpeaker: true` принимают массив реплик. Части референса: `type: input_audio` с `input_audio.data` или `input_audio.url`, `type: text` с `text`, `type: image_url` с `image_url.url`. Допускаются максимум три записи, по одной расшифровке на запись и одно изображение; модель может устанавливать меньшие пределы или отключать референсы. При нескольких записях расшифровка идёт сразу после своей записи. Не отправляйте референсы модели с нулевыми лимитами.

## Ошибки и обрыв аудио

До начала передачи аудио ошибки валидации возвращаются как HTTP-ошибка. После отправки байтов поздняя ошибка закрывает поток: заменить аудио на JSON уже нельзя. Частичный файл не подтверждает завершение генерации. Подробнее о [повторах и списаниях](/ru/docs/audio).

## Решение проблем


**Файл не воспроизводится**


Сначала проверьте HTTP-статус и Content-Type. Для сырого PCM нужны частота и число каналов из заголовков; это не файл MP3 или WAV.


**Голос или скорость отклонены, либо инструкция не повлияла на речь**


Обновите профили выбранной модели и выберите совместимое сочетание. Инструкции по подаче выполняются по возможности; модель без их поддержки игнорирует пожелания.
