Skip to main content
Потоковый API предоставляет возможность транскрибации аудио в реальном времени через WebSocket-соединение. Результаты распознавания приходят по мере обработки аудио, что идеально подходит для live-транскрибации, голосовых интерфейсов и интерактивных приложений.

Производительность

Замеры осуществлялись разными людьми с помощью нашего бенчмарка на разных устройствах и разных интернет-соединениях. Вот результаты: Real-Time Factor < 1 - скорость обработки быстрее real-time.
Данные измерения получены для формата linear16 (raw PCM) без декодирования.При использовании сжатых форматов (opus, ogg-opus, mp3, aac и др.) к задержке добавляется 50–100 мс на декодирование в зависимости от кодека.Фактические значения latency зависят от скорости вашего интернет-соединения и могут отличаться.

Важно Токен передаётся заголовком Authorization: Bearer <ваш_токен> либо query-параметром token. Если переданы оба, приоритет у заголовка.
Из браузера доступен только query-параметр: WebSocket API не позволяет задавать заголовки. Учитывайте, что токен в URL попадает в историю браузера и журналы промежуточных прокси — для серверных интеграций предпочтительнее заголовок.

Пример потоковой транскрибации

Установите WebSocket-соединение с указанием токена авторизации.URL для подключения:
Либо без токена в URL — с заголовком, как в REST-части API:
Параметры подключения:Формат аудио для отправки:
  • Поддерживаемые частоты: 8000, 16000, 22050, 32000, 44100, 48000 Hz
  • Каналы: 1 (mono) или 2 (stereo)
  • Рекомендуемый формат: linear16 (int16 PCM, little-endian)
Для минимальной задержки используйте raw PCM форматы (linear16 или linear32). При использовании сжатых кодеков (opus, mp3 и др.) добавляется 50–100 мс на декодирование. Оптимальный размер отправляемого чанка — от 50 до 300 мс.
После успешного подключения сервер отправит сообщение с конфигурацией:
Отправляйте аудиоданные как бинарные WebSocket-сообщения.
Совет Размер чанков может быть произвольным. Сервер буферизует данные и обрабатывает их блоками по 300ms.
Серверным интеграциям удобнее передавать токен заголовком — тем же, что и в REST-части API. Пример для телефонного профиля: raw PCM16, mono, 16000 Hz.
Параметр additional_headers доступен в библиотеке websockets начиная с версии 14.0. В более ранних версиях используйте extra_headers.
Сервер отправляет промежуточные результаты по мере обработки аудио.Промежуточный результат (type: partial):
Промежуточный результат приходит на каждые 300 мс звука, в том числе с пустым chunk_text. Уже отданный текст не переписывается: новый текст только дописывается в конец, поэтому расшифровку можно собирать по chunk_text.Таймкоды. start и end — секунды от первого отправленного отсчёта звука. Время считается по самому звуку, поэтому не зависит от темпа отправки: ни от пауз между сообщениями, ни от отправки быстрее реального времени. Точность — обычно в пределах 0.1 с, у отдельных слов до 0.2 с.
  • Каждое слово приходит в words один раз — в сообщении, где оно закончилось. Последнее слово, которое ещё произносится, придёт в одном из следующих сообщений.
  • Фраза приходит в phrases, когда после неё наступила пауза не короче 0.6 с, или в последнем сообщении перед final. Обычно это 1–1.5 с после конца фразы. Слова фразы к этому моменту уже пришли в words. Речь без пауз делится на фразы не длиннее 60 с.
  • Склеенные по порядку phrases содержат все слова сессии, ровно по одному разу. Для субтитров и строк расшифровки удобнее брать phrases, для подсветки слов в реальном времени — words.
Пример завершённой фразы:
Финальное сообщение (type: final):При завершении сессии (отправка пустого сообщения или закрытие соединения):
С параметром formatting=true в каждом промежуточном результате появляется блок formatted — тот же текст, но в читаемом виде: со знаками препинания, заглавными буквами, буквой «ё», а числа, даты, время, суммы, телефоны, адреса и e-mail записаны цифрами и символами.
В сообщении config в ответ придёт "formatting": true.
Когда после паузы предложение закончено, оно переходит в committed и больше не изменится:
Как показывать:
  • formatted.text всегда начинается с formatted.committed. Показывайте committed как есть, а остаток text заменяйте целиком в каждом сообщении: хвост незаконченного предложения может переписываться (например, запятая появляется, когда прозвучат следующие слова).
  • Число в конце незаконченного предложения остаётся словами, пока не прозвучит следующее слово или предложение не закончится: «четырнадцать тридцать» → «14:30».
  • Предложение считается законченным после паузы в речи от 0.6 с, если по смыслу оно завершено, или в конце записи. Точку в конце незаконченного предложения сервер не ставит. Длинная речь без пауз фиксируется частями примерно по 40 с (около 100 слов), граница части может прийти посреди предложения. На паузе посреди фразы изредка появляется лишняя точка.
  • Итоговый текст сессии — formatted.text последнего сообщения partial перед final: в нём весь текст зафиксирован (text совпадает с committed).
  • Остальные поля не меняются: chunk_text, full_text, words и phrases — по-прежнему исходный текст без форматирования, таймкоды относятся к нему.
  • Без formatting=true блока formatted в сообщениях нет.
Форматированный текст приходит в том же сообщении, что и исходный, задержка промежуточных результатов обычно увеличивается на единицы–десятки миллисекунд. Если форматирование временно недоступно, часть текста может прийти без знаков препинания (заглавные буквы и числа цифрами сохраняются), а в редком случае блок formatted может перестать обновляться до конца сессии. Распознавание при этом не прерывается: если formatted.text перестал меняться, а full_text растёт, показывайте full_text.
При возникновении ошибок сервер отправляет сообщение с описанием проблемы.Сообщение об ошибке (type: error):
Пример ошибки авторизации:
Коды ошибок:HTTP 403 при подключении — токен не передан или неактивен. Соединение отклоняется на этапе рукопожатия, поэтому описания причины в ответе нет: проверьте, что токен передан заголовком либо query-параметром, и что ключ активен в личном кабинете.Коды закрытия WebSocket:
Пример потоковой транскрибации с микрофона в реальном времени.
Зависимости Для работы с микрофоном установите: pip install pyaudio websockets

Поддерживаемые кодеки

API поддерживает широкий спектр аудиокодеков. Для минимальной задержки рекомендуется использовать raw PCM форматы.
Raw PCM форматы — без накладных расходов на декодирование:Эти форматы обрабатываются напрямую без декодирования, что обеспечивает минимальную задержку.
Lossless:Современные кодеки:Lossy форматы:Контейнерные форматы:
Для интеграции с телефонными системами поддерживаются узкополосные кодеки:
Телефонные кодеки оптимизированы для узкой полосы пропускания. Рекомендуется использовать с sample_rate=8000.

Примеры интеграции с UI

Мы подготовили готовые примеры для интеграции потоковой транскрибации в ваше веб-приложение. Выберите пример для вашего фреймворка:
Пример интеграции потоковой транскрибации в веб-приложение с использованием Web Audio API.
HTML-разметка:
Готовый React-компонент для потоковой транскрибации.
Пример компонента для Vue 3 с Composition API.