# Аудио API

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

Один API-ключ рабочего пространства используется для двух операций:

| Операция                                             | Ручка                           | Успешный ответ              |
| ---------------------------------------------------- | ------------------------------- | --------------------------- |
| [Озвучка (TTS)](/ru/docs/audio-speech)               | `POST /v1/audio/speech`         | Байты аудио                 |
| [Транскрибация (STT)](/ru/docs/audio-transcriptions) | `POST /v1/audio/transcriptions` | JSON с распознанным текстом |

Эти же ручки доступны с префиксом `/api/v1/audio/*`. Указывайте базовый URL один раз, без повторного `/v1`. Создание ключа описано в [авторизации](/ru/docs/authentication). Ключи поставщиков не нужны.

## Выбор модели и голоса

В общем каталоге Аудио находится рядом с текстом, изображениями, видео и Decisions:

```bash
curl --fail-with-body --silent --show-error \
  'https://api.provod.ai/api/models?kind=audio' -o audio-models.json

jq '.data[] | {id, available, audio}' audio-models.json
```

Передавайте точный `id` в поле `model`. В `audio.operations` перечислены `speech` и/или `transcription`, а в `audio.profiles` — проверенные сочетания параметров и ограничения. Профиль озвучки содержит ID голосов, форматы, частоту дискретизации, число каналов и диапазон скорости. Профиль транскрибации — допустимые характеристики записи, языки и дополнительные возможности. Выбирайте совместимый профиль целиком: значения из разных профилей не всегда можно сочетать.

`available` отражает доступность в каталоге и наличие тарифа, но не гарантирует ответ поставщика в конкретный момент. Права пространства, лимиты ключа и баланс проверяются при запросе. `/v1/models` предназначен для текстовых клиентов; каталог аудио — `/api/models?kind=audio`.

Послушайте примеры в галерее «Аудио → Озвучка» кабинета, затем выберите модель и голос. Галерея помогает оценить звучание; новая генерация не обязана в точности повторять пример. Один голос может работать с несколькими моделями. В API нужен публичный ID `voice`, а не отображаемое имя или ID карточки галереи.

## Тарифы и списания

Смотрите `audio.pricing` нужной операции. У тарифа есть `currency`, `revision` и `components`. Компонент задаёт `meter`, `unitQuantity`, `unitPrice`, `roundingIncrement` и `minimumQuantity`. Для символов указан способ подсчёта, для длительности — группировка каналов. Поэтому короткая запись может оплачиваться по минимальной длительности. Нельзя считать стоимость аудио по тарифу текстовых токенов или переносить единицу оплаты с одной модели на другую.

Пользовательский тариф фиксируется при запуске операции. Для аудио действуют баланс и лимиты расходов API-ключа. Итоговое списание смотрите в [расходах](/ru/docs/usage-costs). Необязательный блок `usage` транскрибации описывает объём обработки и может отсутствовать. Искусственное значение `usage.cost` в USD в ответ не подставляется.

## Запросы, задачи и повторы

Публичный API возвращает результат в том же HTTP-запросе. Озвучка отдаёт бинарный поток, транскрибация ожидает JSON. В кабинете генерация выполняется фоновой задачей и появляется в истории. Ссылка на задачу кабинета не является публичной ручкой опроса API.

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

## Совместимость и дополнительные возможности

Формы запросов соответствуют интерфейсам [OpenRouter TTS](https://openrouter.ai/docs/api/api-reference/tts/create-speech) и [STT](https://openrouter.ai/docs/api/api-reference/stt/create-transcription). Каталог, ограничения, формат ошибок и учёт стоимости определяются нашей платформой. ID моделей и голосов другого сервиса не становятся доступными автоматически.

Обе операции принимают `provider.data_collection` (`allow`/`deny`) и `provider.zdr`. Строгая политика требует проверенного совместимого маршрута; неизвестные свойства маршрута не считаются подтверждением. `provider.options` содержит JSON-настройки по ключам поставщиков там, где они поддержаны. Необязательные `session_id` и `user` ограничены 256 символами; `trace` — объект метаданных JSON. Эти поля не подключают интеграции журналирования другой платформы.

Генерация музыки, разговор в реальном времени, перевод и постоянное обучение голосов в эти ручки не входят. Несколько говорящих, записи-референсы, разделение спикеров и ключевые термины требуют явной поддержки модели.

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


**Модель отсутствует или недоступна**


Обновите каталог аудио и проверьте точный ID, операцию и доступ рабочего пространства. Модель поставщика доступна у нас после публикации её маршрута и тарифа.


**Запрос завершился по таймауту**


Проверьте расходы до повторного запроса. Отсутствие ответа не означает, что обработка и списание не начались; подробнее в [ошибках](/ru/docs/errors).
