О транскрибации
Transcription API распознаёт речь из аудио- или видеофайла и возвращает текстовую расшифровку. Под капотом — модели Whisper (через Deepgram).
Как это работает
Есть два режима, оба на адресе POST /v1/audio/transcriptions — режим выбирается по Content-Type запроса.
Асинхронный, по ссылке (основной)
Content-Type: application/json. API принимает готовую ссылку на файл (audio_url), доступную по прямой публичной ссылке. Метод /create создаёт задачу и сразу возвращает её id, а результат забирается методом /result или доставляется на callback_url (webhook).
Модели deepgram-whisper-*, размер файла не ограничен, до 2 часов. Подходит для длинных записей и webhook-сценариев.
Синхронный, загрузкой файла (OpenAI-совместимый)
Content-Type: multipart/form-data. Вы загружаете файл и получаете расшифровку в ответе на тот же запрос. Формат запроса и ответа совместим с OpenAI, поэтому работает их официальный SDK — достаточно поменять base_url.
Модель whisper-1, лимит 25 МБ на файл. Подробности — в разделе OpenAI-совместимый режим.
Доступные модели
| Модель | Описание |
|---|---|
deepgram-whisper-tiny | Самая быстрая и дешёвая, ниже точность |
deepgram-whisper-medium | Баланс скорости и качества |
deepgram-whisper-large | Максимальная точность |
whisper-1 | Whisper от OpenAI, только синхронный режим |
Поддерживаемые форматы
Асинхронный режим: mp3, mp2, wav, flac, aac, ogg, oga, opus, m4a, mp4, mov, 3gp, alac, webm, mka, wma, wmv, amr, aiff, ac3, avi, flv, ts, mpg, au.
Синхронный режим принимает более узкий список — только то, что поддерживает OpenAI: flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm.
Формат в обоих режимах определяется по реальному содержимому файла, а не по расширению. Файлы в неподдерживаемых форматах отклоняются сразу, без списания средств (в асинхронном режиме — 415 / code 11, в синхронном — 400 / unsupported_format).
Ограничения
- Формат ссылки (асинхронный режим):
audio_url— прямая публичная ссылка (http/https) на аудио или видео. - Размер файла (синхронный режим): до 25 МБ. В асинхронном режиме размер не ограничен.
- Максимальная длительность: 2 часа. Более длинные файлы отклоняются с ошибкой
Audio is too long. - Минимальная длительность: 1 секунда. Более короткие файлы (в т.ч. с нулевой длительностью) отклоняются с ошибкой
Audio is too short.
Требования к хостингу файла
Чтобы задача прошла успешно, хостинг файла должен:
- отдавать файл по прямой ссылке без cookies, авторизации и фильтрации по User-Agent;
- не использовать антибот-защиту (Cloudflare и аналогичные CDN-фильтры не подойдут);
- поддерживать HTTP Range-запросы — без них не определяется длительность у
ogg/opus/webm/mka; - возвращать корректный Content-Length;
- быть доступным из-за пределов вашей сети (не intranet, не localhost, не приватные IP).
Надёжные варианты: объектные хранилища (S3, Yandex Object Storage) с публичной ссылкой, собственный CDN без антибот-фильтров.
Если файл недоступен нашему серверу, запрос отклоняется сразу (400 / code 12, без списания). Если файл доступен нам, но недоступен провайдеру, задача завершится с error_title: "SOURCE_UNREACHABLE" — средства вернутся автоматически.