provod.ai / docs
Аудио API

Создать расшифровку (STT)

Распознавание файлов, Base64 и записей по URL с временными метками и разделением спикеров.

Обновлено

POST /v1/audio/transcriptions принимает JSON или multipart/form-data и возвращает JSON. Передавайте API-ключ рабочего пространства в Authorization: Bearer.

Загрузить запись

Выберите модель с операцией transcription в каталоге аудио. Модель из примера принимает моно PCM WAV 16 кГц; для других форматов сначала проверьте актуальный профиль.

Terminal
export PROVOD_API_KEY="sk_..."
export AUDIO_MODEL="speechkit-stt-general"

curl --fail-with-body --silent --show-error \
  https://api.provod.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -F "model=$AUDIO_MODEL" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "response_format=json" -o transcript.json

Успешный ответ по умолчанию содержит text. Необязательный блок usage может отсутствовать. curl -F сам задаёт границу multipart: не устанавливайте Content-Type вручную.

Передать Base64 или URL

В JSON объект input_audio содержит ровно один источник. Для данных внутри запроса передавайте канонический Base64 без префикса data: и укажите format:

transcribe.mjs
import { readFile } from "node:fs/promises";

const response = await fetch("https://api.provod.ai/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PROVOD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: process.env.AUDIO_MODEL,
    input_audio: {
      data: (await readFile("recording.wav")).toString("base64"),
      format: "wav",
    },
    response_format: "json",
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log((await response.json()).text);

Другой вариант — общедоступный HTTP(S) URL. Замените демонстрационный адрес на URL своего файла:

URL request body
{
  "model": "speechkit-stt-general",
  "input_audio": {
    "url": "https://media.example.com/recording.wav",
    "format": "wav"
  },
  "response_format": "json"
}

Платформа скачивает и проверяет файл перед распознаванием. Адреса внутренних и локальных сетей, а также URL с учётными данными запрещены. Если format отсутствует, формат должен определяться по расширению в пути; для подписанных адресов и путей без расширения укажите его явно. Не передавайте одновременно data и url.

Поля запроса

ПолеТипПоведение
modelстрока, обязательноПубличный ID модели с операцией transcription
input_audioобъект, только JSONdata + format или url + необязательный format
fileбинарный файл, только multipartОдин аудио- или видеофайл
languageстрокаДвухбуквенный код ISO-639-1 строчными буквами, например en или ru; отсутствие требует поддержки автоопределения
response_formatjson или verbose_jsonПо умолчанию json
timestamp_granularitiesмассив word/segmentТолько для verbose_json; при json игнорируется
diarizeлогическое значениеМетки спикеров; нужны поддержка модели и verbose_json, при этом добавляются метки слов
keytermsмассив строкПодсказки распознаванию, если поддержаны; до 1000 терминов по 1–100 символов, у модели могут быть меньшие лимиты
temperatureчислоТолько в опубликованном диапазоне выбранной модели
provider, session_id, user, traceобъекты или строкиОбщие параметры аудио

В multipart передавайте метки повторяющимися полями timestamp_granularities[], diarize — как true/false, а provider и trace — строками JSON. Для терминов используйте JSON-массив в одном поле: -F 'keyterms=["Acme","SpeechKit"]'. Повторяющиеся keyterms[] тоже работают для коротких списков, но всего разрешено 32 текстовых поля и один файл; JSON-массив не расходует отдельное поле на каждый термин. Не передавайте обе формы массива одновременно. Неизвестные поля отклоняются, а не пересылаются без проверки.

Временные метки и ответ

Terminal
curl --fail-with-body --silent --show-error \
  https://api.provod.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -F "model=$AUDIO_MODEL" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=word" \
  -F "timestamp_granularities[]=segment" -o transcript.json
Example verbose response
{
  "text": "Hello world",
  "task": "transcribe",
  "duration": 2.4,
  "words": [
    {"word": "Hello", "start": 0.2, "end": 0.8},
    {"word": "world", "start": 0.9, "end": 1.5}
  ],
  "segments": [{"id": 0, "text": "Hello world", "start": 0.2, "end": 1.5}]
}

Время указано в секундах от начала аудио. Дополнительные поля language, оценки уверенности, метки спикеров и сущности появляются, только если их вернула модель. Отсутствие оценки уверенности не означает нулевую уверенность. Разделение спикеров не устанавливает реальные личности людей.

Ограничения файлов и моделей

Для multipart и Base64 внутри JSON допускается не более 25 МиБ (26 214 400 байт) исходного файла. Base64 увеличивает JSON, но лимит применяется к декодированным байтам. При импорте по URL предел — 100 МиБ (104 857 600 байт). У модели могут быть меньшие ограничения, а также пределы длительности, кодека, частоты и числа каналов. Прямая загрузка в кабинете имеет отдельные лимиты и не увеличивает лимит multipart или Base64 в API.

Распознаваемые обозначения форматов: wav, mp3, mp4, m4a, ogg, webm, flac, pcm, mov, mpeg, mpg. Это список форматов входа, а не обещание поддержки любой моделью. В частности, сырой PCM не содержит описания характеристик и должен пройти проверку медиа; для PCM-записей используйте WAV.

Видео принимается, если содержит декодируемую звуковую дорожку. Валидатор извлекает звук для распознавания; содержимое кадров не анализируется. Для multipart указывайте реальный MIME-тип, например file=@recording.mp4;type=video/mp4. Извлечённое аудио должно соответствовать профилю модели. Видео без звука или повреждённый файл отклоняется.

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

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