Главный гайд

Как распознать русскую речь в текст через API: пошаговое руководство

15 минут чтения · 1 сентября 2026

Распознавание речи (speech-to-text, STT) превращает аудио в структурированный текст: слова, таймкоды и метки говорящих. В этом руководстве мы пройдём весь путь – от понимания того, как работает STT и почему русский язык сложнее английского, до рабочего Python-скрипта, который отдаёт расшифровку с точностью до секунды. Отдельно разберём диаризацию, экспорт субтитров и ошибки, из-за которых чаще всего спотыкаются при интеграции.

Зачем нужна транскрибация

Ручная расшифровка медленная, дорогая и неточная. Час аудио занимает у человека от трёх до пяти часов, а на длинных записях с несколькими голосами, акцентами и технической лексикой ошибки неизбежны: усталость, незнакомые термины, пропущенные реплики. STT-API справляется с тем же объёмом за минуты и сразу возвращает структурированный результат – каждое слово привязано к секунде, когда оно прозвучало.

Типичные сценарии, где это нужно: расшифровка звонков колл-центра и контроль качества обслуживания; субтитры к видео, вебинарам и роликам для соцсетей; протоколы интервью, подкастов и совещаний; разметка аудио для машинного обучения; проверка произношения в EdTech. Общее у всех случаев одно – текстовый результат нужен быстро, дёшево и с возможностью найти нужный момент по таймкоду, а не переслушивать запись целиком.

Для русского языка задача сложнее, чем для английского. В русском больше словоформ – падежи, склонения, спряжения, – свободный порядок слов и огромное количество имён собственных, фамилий и аббревиатур. Поэтому главный критерий при выборе сервиса – реальная точность именно на русской речи, а не цифры из маркетинговых таблиц.

Как работает распознавание речи

Современный STT – это нейросеть, обученная на тысячах часов размеченной речи. Входной аудиофайл нарезается на короткие окна, каждое превращается в спектрограмму – «картинку» распределения частот во времени, – а модель предсказывает по ней последовательность символов или слов. Затем результат проходит языковую модель, которая расставляет знаки препинания и выбирает осмысленные слова вместо случайных наборов звуков.

Качество оценивают метрикой WER (word error rate) – долей слов, распознанных неверно. WER 5% означает, что каждое двадцатое слово с ошибкой. На реальных звонках с шумом и несколькими говорящими WER обычно выше, чем на чистой студийной записи, поэтому честные сервисы указывают, на каких данных измерена точность, и дают её проверить на своём файле.

Второй важный элемент – таймкоды и уверенность. Хороший API возвращает не просто текст, а сегменты с границами по времени и confidence – оценку уверенности модели в каждом слове. Это позволяет подсвечивать сомнительные места вместо сплошной вычитки всего текста и строить по ним интерфейсы проверки.

Свой Whisper или готовое API?

Можно развернуть открытую модель Whisper на своём сервере – это популярно, когда объёмы большие и стабильные, а требования к конфиденциальности жёсткие. Но у этого пути есть скрытая цена: нужна GPU или мощный CPU, обслуживание, обновление моделей, очереди и мониторинг. Внезапный рост нагрузки означает покупку железа, а не просто переход на следующий тариф.

Готовый API снимает всю инфраструктуру: вы платите за минуту аудио, а не за простой сервера. Это выгодно на старте и при переменной нагрузке, когда точный объём заранее неизвестен. К тому же боевой STT – это не только модель, но и постобработка: таймкоды, диаризация, субтитры и очистка звука, которые при self-host приходится собирать отдельно.

Правило простое: если у вас стабильные сотни часов в день и своя команда инфраструктуры – можно смотреть в сторону self-host. Если объёмы плавающие и важна скорость запуска – API окупается тем, что интеграция занимает часы, а не недели.

Как выбрать API

Сравнивайте сервисы по пяти критериям. Точность: WER на русском, в идеале – на данных, похожих на ваши: звонки, интервью или лекции. Цена: считайте за минуту аудио, а не за запрос, и обращайте внимание на минимальный порог оплаты. Поддержка русского: модель должна быть обучена именно на русской речи, а не «уметь всё понемногу». Возможности: слово-уровневые таймкоды и диаризация – разметка того, кто говорит. Скорость: для коротких файлов нужен синхронный ответ за секунды, для длинных – асинхронные задачи с опросом статуса.

Voice kit API закрывает эти пункты из коробки: русский без дополнительной настройки, таймкоды до отдельного слова, диаризация спикеров и потоковая транскрибация по WebSocket для звонков в реальном времени. Детали и цены – смотрите тарифы.

Получение API-ключа

Зарегистрируйтесь в кабинете – ключ создаётся автоматически и доступен в разделе API. Бесплатный тариф включает 150 аудио-минут в месяц – этого хватает, чтобы прогнать интеграцию на реальных файлах и снять замеры точности до покупки.

Ключ передавайте в заголовке X-Api-Key каждого запроса. Не храните его в коде и не коммитьте в репозиторий – используйте переменные окружения или .env-файл, который не попадает в git. Если ключ засветился в логах или утёк, перевыпустите его в кабинете: старый перестанет работать мгновенно.

Код на Python

Установите SDK одной командой – либо работайте с API через обычные HTTP-запросы. Самый быстрый способ для коротких файлов – синхронный метод, который возвращает результат сразу:

pip install voicekit-client

from voicekit import VoiceKitClient

client = VoiceKitClient(api_key="rtt_…")

transcript = client.transcribe_sync("meeting.mp3")
print(transcript["transcript"])

for segment in transcript["segments"]:
    print(segment["start"], segment["end"], segment["text"])

Для длинных записей – от пары минут и выше – используйте асинхронный режим: загружаете файл, получаете job_id и опрашиваете статус, пока он не станет completed или failed:

job = client.transcribe("meeting.mp3", language="ru", diarization=True)
result = client.get_transcription_job(job["job_id"])
while result["status"] not in ("completed", "failed"):
    result = client.get_transcription_job(job["job_id"])

print(result["transcript"])

Параметр language подсказывает модели язык записи, а diarization включает разметку говорящих – о ней подробнее ниже. Если язык известен заранее, передавайте его явно: это почти всегда улучшает точность на коротких и неоднозначных фразах.

Какой режим выбрать? Синхронный подходит для файлов до трёх минут: один запрос – один ответ, никакого опроса статуса. Асинхронный нужен для длинных записей и пачек файлов: вы отправляете загрузку, сервис обрабатывает в фоне, а вы забираете результат, когда он готов. В асинхронном режиме удобно добавить webhook – адрес, на который придёт уведомление о завершении, чтобы не опрашивать статус вручную.

Что возвращает API и как читать ответ

Ответ содержит transcript – итоговый текст целиком – и segments, список сегментов с границами по времени. Внутри каждого сегмента лежат words – слово-уровневые таймкоды word, start, end и confidence:

{
  "transcript": "Сегодня мы обсудим план запуска.",
  "segments": [
    {
      "start": 0.0,
      "end": 4.2,
      "text": "Сегодня мы обсудим",
      "speaker": "Speaker 1",
      "words": [
        {"word": "Сегодня", "start": 0.0, "end": 0.9, "confidence": 0.98}
      ]
    }
  ]
}

Если включена диаризация, у каждого сегмента появляется speaker – модель размечает, кому принадлежит реплика. Для звонков и интервью это позволяет собрать текст по каждому участнику отдельно.

Обратите внимание на confidence: слова с низкой уверенностью стоит подсвечивать в интерфейсе, чтобы оператор быстро перепроверял сомнительные места, а не вычитывал весь текст целиком.

Диаризация: кто говорит

Диаризация отвечает на вопрос «кто говорил в этот момент». Модель нарезает запись на реплики и присваивает им метки спикеров, даже если не знает их имён – Speaker 1, Speaker 2 и так далее. Имена вы сопоставляете сами, если они вам известны.

Включается одним параметром diarization=True. Подходит для звонков поддержки, интервью, переговоров и совещаний: вместо сплошного потока текста вы сразу видите диалог с указанием, кто что сказал.

Субтитры и экспорт

Для видео и вебинаров не нужно вручную собирать SRT из таймкодов. Вызовите GET /v1/transcribe/{job_id}/subtitles?format=srt – сервис отдаст готовый файл субтитров, который сразу подключается к ролику на YouTube или в плеере.

Поддерживаются форматы SRT и VTT. SRT – универсальный формат для видеоредакторов и хостингов, VTT удобен для веб-плееров и позволяет задавать стили. Оба формата строятся из тех же таймкодов, что и обычный ответ, поэтому ничего дополнительно настраивать не нужно.

Ошибки и лимиты

Основные коды: 401 – неверный или отозванный ключ, 413 – файл превышает допустимый размер, 429 – исчерпан лимит тарифа. Обрабатывайте их в коде: при 429 делайте паузу и повторяйте запрос с экспоненциальной задержкой, при 401 – перевыпустите ключ.

Полный список кодов, лимиты и примеры запросов – смотрите документацию.

Как повысить точность

Качество аудио влияет на результат сильнее, чем смена модели. Записывайте в 16 кГц и выше, без сильной компрессии и эха: MP3 с битрейтом 64 кбит/с заметно хуже WAV или 192+ кбит/с. Один говорящий на канал и минимум фонового шума дают больше, чем любые настройки.

Если язык известен, передавайте language явно – модель не тратит силы на определение и меньше ошибается на коротких фразах. Диаризацию включайте только когда говорящих несколько: на монологе она не нужна и может добавить ошибок.

Для телефонных записей используйте формат 8 кГц моно, принятый в телефонии, и не перекодируйте его в 16 кГц – это не добавит качества, а только раздует файл. Длинные записи с перебивками и паузами полезно разбить на смысловые фрагменты до отправки, если вам важна максимальная точность.

Частые ошибки при интеграции

Первая – забыть заголовок X-Api-Key или перепутать его с query-параметром. Ключ передаётся только в заголовке; в URL его не подставляйте, иначе он попадёт в логи прокси и историю браузера.

Вторая – опрашивать статус асинхронной задачи без паузы. Сотни запросов в секунду не ускорят обработку, но быстро упрутся в лимит 429. Делайте паузу между опросами или используйте webhook, чтобы получить результат сразу по готовности.

Третья – не проверять размер и формат файла до отправки. Сервис принимает wav, mp3, ogg и flac с ограничением по размеру; лишний гигабайт видео лучше конвертировать в аудио до загрузки, иначе запрос отклонится с 413 ещё до распознавания.