provod.ai / docs
Аудио API

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

Генерация речи в MP3 или PCM с выбором модели и голоса через публичный API.

Обновлено

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

Получить MP3

Выберите модель и голос в каталоге аудио. ID из примера должны быть доступны в вашем развёртывании. Для команд нужны curl и jq.

Terminal
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():

speech.mjs
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_formatmp3 или pcmПо умолчанию pcm; выбирайте опубликованный профиль вывода
speedположительное числоМножитель скорости в диапазоне minSpeed–maxSpeed выбранного профиля
instructionsстрокаПожелания к подаче речи; маршрут без поддержки инструкций может их игнорировать
input_referencesмассивРеференсы в пределах опубликованных ограничений модели
provider, session_id, user, traceобъекты или строкиОбщие параметры аудио

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

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

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

Terminal
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 уже нельзя. Частичный файл не подтверждает завершение генерации. Подробнее о повторах и списаниях.

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

На этой странице