FreedomSpeech
Документация / API распознавания речи

API распознавания речи

Актуальная спецификация ASR: HTTP (raw PCM), HTTP (файл), WebSocket-стриминг, форматы аудио, ответы и метрики качества.

Эндпоинты

GET
https://4div1t9inbkp96-644111f8-8000.proxy.runpod.net/health
POST
https://4div1t9inbkp96-644111f8-8000.proxy.runpod.net/transcribe
POST
https://4div1t9inbkp96-644111f8-8000.proxy.runpod.net/transcribe_file
WSS
wss://4div1t9inbkp96-644111f8-8000.proxy.runpod.net/ws/transcribe

Форматы аудио и как отправлять

1) HTTP /transcribe (raw PCM16 в body)

  • Формат: raw PCM16, signed int16, little-endian, 16 kHz, mono, без контейнера (не WAV/MP3).
  • Запрос: Content-Type: application/octet-stream, в body — сырой PCM.
  • Важно: если источник WAV, отправляйте PCM без WAV-заголовка (часто пропускают первые 44 байта) или декодируйте в raw PCM заранее.

2) HTTP /transcribe_file (файл целиком через multipart)

  • Формат запроса: multipart/form-data
  • Поле: file
  • Форматы: как минимум WAV; MP3 может быть разрешён конфигурацией сервера, иначе вернётся 400 (unsupported format).
  • Лимит длительности: до 2 часов (проверка на сервере: > 7200 секунд отклоняется).
PowerShell
curl -X POST "https://4div1t9inbkp96-644111f8-8000.proxy.runpod.net/transcribe_file" `
  -F "file=@C:\path\to\audio.wav"

3) WebSocket /ws/transcribe (стриминг raw PCM16)

  • Бинарные WS-сообщения: raw PCM16 (signed int16, little-endian), mono, 16 kHz, без контейнера.
  • Завершение сессии: текстовая команда {"type":"stop"}.
  • Сервер режет речь по VAD и отправляет частичные финальные гипотезы (несколько сообщений с is_final=true по сегментам).
  • Критично: корректный PCM-формат, стабильное соединение, разумный размер чанка.

Размер чанка и компромиссы

Слишком маленькие чанки: выше overhead (больше WS-фреймов), чаще обработка, выше риск таймаутов, ниже throughput.

Большие чанки: лучше throughput, но выше latency до первого полезного ответа.

Для real-time: минимальный стабильный чанк (ориентир: 2048 байт ≈ 64 мс).
Если нужна не интерактивность, а итоговый текст целиком — эффективнее /transcribe_file.

Формат ответов

HTTP /transcribe (raw PCM)

JSON содержит:

  • text — текст с пунктуацией (если включено)
  • text_raw — сырой текст (без пунктуации)
  • gpu, time_ms — служебные метрики (могут присутствовать)

HTTP /transcribe_file (файл)

Сервер возвращает только поле text:

  • {"text":"..."} — при успешном распознавании.
  • {"text":""} — если речь не распознана.

WebSocket /ws/transcribe

Поток JSON-сообщений:

  • Сегментные гипотезы: text, text_raw, is_final
  • Метрики: gpu, time_ms/inference_ms, latency_ms, audio_duration_ms
  • Финал: {"type":"stopped","status":"ok"}
Важно: в /transcribe_file пунктуация добавляется пер-сегментно с последующей склейкой в итоговый text. В WebSocket-ответах текст идёт без отдельного пунктуационного постпроцессора.

Метрики качества (WER)

Model ISSAI-KSC2 CV-kaz FLEURS-kaz Golos-crowd CV-rus FLEURS-rus
abilmansplus/whisper-turbo-kaz-rus-v1 8.92% 13.34% 13.60% 8.95% 20.73% 16.34%
openai/whisper-large-v3-turbo 70.30% 47.42% 23.68% 26.25% 8.78% 5.21%

Смешанный язык (ru/kk в одном предложении)

Сервер отдает результат короткими VAD-сегментами, поэтому распознавание не зависит от «языка всего предложения». Модель решает задачу локально по текущему фрагменту, и смешение русских и казахских слов не ломает распознавание так, как в системах с жёстким выбором одного языка на всё предложение.