Перейти к содержанию

Обзор Speech-Expert API

Speech-Expert API — это сервис распознавания и синтеза речи. Он поддерживает совместимые методы Yandex SpeechKit и OpenAI Audio API, поэтому для поддержанных методов можно использовать привычные клиенты и SDK — например, openai.

Начните с быстрого старта: подтвердите email, создайте API-ключ и отправьте первый запрос через cURL или Python.

С помощью Speech-Expert API вы можете:

Бесплатный старт

После регистрации новый аккаунт получает стартовые кредиты автоматически. Актуальный размер бонуса и примеры доступного объёма собраны в блоке «Бесплатный старт» на главной. Фактическое списание зависит от выбранной STT-модели, длительности обработанного аудио и включённого разделения участников; итоговая ставка показывается до запуска и в личном кабинете.

Языки распознавания

Готовые аудио- и видеофайлы можно распознавать на шести языках. Живой поток с промежуточным текстом доступен на русском, английском, казахском, кыргызском, узбекском и таджикском:

Язык Код STT v1/v3 Готовый файл Живой WebSocket/gRPC
Русский ru-RU да да
Английский en-US да да
Казахский kk-KZ да да
Кыргызский ky-KG да да
Узбекский uz-UZ да да
Таджикский tg-TJ да да

При потоковом распознавании текст появляется по мере обработки аудио. Промежуточный результат (partial) может уточняться; окончательный результат (final) завершает отдельную фразу. Форматы подключения и параметры запросов описаны в разделах WebSocket и gRPC.

Для длинных, в том числе многочасовых записей на русском, английском, казахском, кыргызском, узбекском и таджикском доступна потоковая загрузка файла в браузере: текст появляется до завершения обработки всей записи. Для интеграций можно передавать исходный файл частями через WebSocket либо декодированное аудио через PCM WebSocket/gRPC.

В Playground сначала выберите источник: «Файл», «Ссылка», «Запись» или «Живые субтитры», затем укажите «Язык записи». Для файла включите «Текст по мере обработки», если хотите получать расшифровку до завершения обработки всего файла. Дополнительные настройки обычного распознавания собраны в разделе «Параметры обработки».

В «Живых субтитрах» потоковое распознавание выбирается автоматически по языку. Текст появляется во время речи; сеанс не сохраняется, а расшифровку можно скопировать или скачать. Режим «Запись» позволяет записать аудио в браузере и при необходимости распознать его после остановки.

Для API используйте код языка и параметры из справочника выбранного метода. В PCM WebSocket/gRPC указывайте совместимое значение model; в маршруте длинного файла /api/stt/v1/file-stream/ws оно выбирается автоматически по языку, если не задано явно.

Имена моделей

В семействе SpeechExpert-STT имя указывает язык и режим: RU, EN, UZ, KK или TG — язык; суффикс -stream — получение результатов по мере поступления аудио. Например, SpeechExpert-STT-UZ используется для готового файла, а SpeechExpert-STT-UZ-stream — для потока. Передавайте идентификатор точно как в справочнике и отдельно указывайте совместимый код языка.

Язык Файловая модель SpeechExpert Потоковая модель
Русский SpeechExpert-STT-RU SpeechExpert-STT-RU-stream
Английский SpeechExpert-STT-EN Parakeet-EN
Казахский — SpeechExpert-STT-KK-stream
Кыргызский — GigaAM-Multilingual-Large-CTC
Узбекский SpeechExpert-STT-UZ SpeechExpert-STT-UZ-stream
Таджикский — SpeechExpert-STT-TG-stream

Для файлов также доступны Parakeet-EN, GigaAM-Multilingual-Large-CTC, Whisper-Large-v3-Turbo, ElevenLabs-Scribe-v2 и gemini-3.5-transcribe. Их языки и ограничения указаны в таблице файловых моделей.

Для потока на 75 языках сервиса доступна ElevenLabs-Scribe-v2-Realtime через WebSocket, gRPC STT v3 и потоковую загрузку файла. Она возвращает промежуточные и окончательные фразы через ElevenLabs без отдельного файлового уточнения. Подробнее — Scribe Realtime.

Готовую расшифровку можно использовать для резюме и исследовательского отчёта. Для саммаризации можно независимо выбрать BCP-47 язык результата. Полный перевод транскрипта выполняется отдельным LLM-методом, сохраняя исходный текст и его таймкоды.

Многоязычность ASR не переносится автоматически на классификацию эмоций. Эмоциональная динамика включается параметром emotionAnalysis=true только для русской речи; для казахского, кыргызского, узбекского и таджикского качество не заявляется. Результат — вероятностный акустический сигнал для перехода к фрагменту и ручной проверки, а не объективная оценка человека.

Подробная матрица моделей и временной разметки приведена в разделе STT v1. OpenAI-совместимый метод использует короткие коды ru, en, kk, ky, uz, tg, а STT v3 — поле recognitionModel.languageRestriction.languageCode.

Способы распознавания речи

В зависимости от длительности записи и требований к задержке выберите подходящий способ.

Способ Когда использовать Протокол
Синхронное распознавание Короткие записи, ответ в одном HTTP-запросе HTTP POST /api/stt/v1
Фоновый STT v1 Playground, видео по ссылке, приватный режим и тот же расширенный ответ v1 HTTP POST /api/stt/v1:recognizeAsync + операции
Асинхронное распознавание v3 Длинные записи и SpeechKit-совместимые события/аналитика HTTP POST /api/stt/v3/recognizeFile + операции
Длинный файл с промежуточными результатами Исходный файл до 10 ГиБ частями, текст и прогресс во время обработки WebSocket
Живой поток WebSocket Микрофон или декодированная запись, mono PCM16 16 кГц и простой JSON WebSocket
Живой поток gRPC Телефония, protobuf, mono или многоканальный interleaved PCM gRPC
OpenAI-совместимый файловый стрим Целый файл загружается одним запросом, результат выдаётся как SSE HTTP + SSE

Способы синтеза речи

Способ Когда использовать Протокол
Синтез длинного текста Фоновая озвучка длинных текстов с отслеживанием прогресса и скачиванием готового WAV HTTP + операции
REST API v1 Интеграции, Higgs-разметка, выбор формата и HTTP-streaming HTTP POST /api/tts/v1
OpenAI-совместимый синтез Приложения на OpenAI SDK со встроенными голосами HTTP POST /api/v1/audio/speech
Потоковый синтез Двунаправленная интеграция по protobuf gRPC

Аутентификация

Все вычислительные методы API (распознавание, синтез, классификация эмоций, операции, OpenAI-совместимые эндпоинты, gRPC) требуют аутентификации. Передавайте действующий API-ключ в заголовке Authorization:

Authorization: Api-Key <ваш-ключ>

API-ключ должен быть заранее создан и активен. Запрос без ключа или с несуществующим либо неактивным ключом завершается ошибкой 401 Unauthorized.

Схемы Api-Key и Bearer

API принимает обе схемы — Authorization: Api-Key <ключ> и Authorization: Bearer <ключ>, а также ключ без префикса. Схемы работают одинаково для HTTP REST, gRPC и потокового распознавания по WebSocket. Схема Bearer позволяет подключать стандартные клиенты (например, openai) без дополнительной настройки.

Вместо API-ключа принимается также активная сессия портала (cookie) — её использует веб-интерфейс.

Форматы аудио

API принимает большинство распространённых аудио- и видеоконтейнеров: в STT v1 формат определяется автоматически. WAV поддерживается как с целочисленными PCM-сэмплами, так и с IEEE Float (wFormatTag=3). HTTP v1 не принимает raw PCM без заголовка: заверните его в WAV или используйте WebSocket/gRPC. В STT v3 объект audioFormat использует строгий oneof: для MP3 и OGG/Opus необходимо явно передать containerAudio, а заявленный тип проверяется по фактическим байтам. Подробности — в разделах STT v1 и STT v3.

Ограничения

Параметр Значение
Максимальный размер multipart-загрузки аудио/видео (STT v1, OpenAI Audio, перевод и сохранение записи) 500 МБ
Максимальный размер файла, скачиваемого по uri (STT v3) 500 МБ
Максимальный размер видео по videoUrl / длительность 200 МБ / 4 часа по умолчанию
Максимальная длина текста для синтеза (TTS v1) 5000 символов
Максимальная длина текста (OpenAI /audio/speech) 4096 символов

Начало работы

Ниже — минимальные примеры для Speech Expert. Замените $API_KEY на действующий API-ключ.

Распознать речь

curl -X POST "https://speech-expert.ru/api/stt/v1" \
  -H "Authorization: Api-Key $API_KEY" \
  -F "audio=@audio.wav" \
  -F "lang=ru-RU" \
  -F "channelMode=mono"

В ответе сервис возвращает распознанный текст:

{
  "result": "распознанный текст"
}

Для казахского, кыргызского или узбекского файла явно выберите locale и многоязычную модель. Например, для казахского:

curl -X POST \
  "https://speech-expert.ru/api/stt/v1?model=GigaAM-Multilingual-Large-CTC" \
  -H "Authorization: Api-Key $API_KEY" \
  -F "audio=@kazakh.wav" \
  -F "lang=kk-KZ" \
  -F "channelMode=mono"

Для кыргызского и узбекского используйте соответственно ky-KG и uz-UZ.

Синтезировать речь

curl -X POST "https://speech-expert.ru/api/tts/v1" \
  -H "Authorization: Api-Key $API_KEY" \
  -d "text=Привет, мир!" \
  -d "voice=elena-speech-expert-tts" \
  -d "format=wav" \
  --output speech.wav

В ответе сервис возвращает аудиофайл.

Проверить доступность сервиса

curl https://speech-expert.ru/health

{
  "status": "ok",
  "service": "speech-tech-api"
}

Справочник методов

Метод Путь Назначение
GET /health Проверка доступности сервиса
POST /api/stt/v1 Синхронное распознавание: mono с опциональной диаризацией или раздельное распознавание физических stereo-каналов
POST /api/stt/v1:recognizeAsync Асинхронное распознавание с получением результата по идентификатору операции
POST /api/stt/v1:summarize Новая версия резюме готовой расшифровки без ASR
POST /api/stt/v1:translate Полный перевод готовой расшифровки с привязкой к исходным фрагментам
POST /api/stt/v1:summarizeDigest Дайджест нескольких сохранённых записей
POST /api/stt/v1:derive Voice Inbox, учебный набор, поручения или Creator Pack
POST /api/stt/v1:askArchive Ответ по архиву с источниками
WS /api/stt/v1/ws Живые субтитры без сохранения
POST /api/stt/v1:recognizeEmotion Классификация эмоций в аудио; метод также доступен по адресу /api/emotion/v1
GET, POST /api/account/recordings Список и сохранение записей; требуется portal-cookie
GET, PATCH, DELETE /api/account/recordings/{id} Чтение, обновление или полное удаление записи; требуется portal-cookie
GET, DELETE /api/account/recordings/{id}/media Получение или отдельное удаление аудио; транскрипт сохраняется
POST /api/stt/v3/recognizeFile Асинхронное распознавание файла
GET /api/stt/v3/getRecognition?operationId={id} Конечный поток событий распознавания
POST /api/tts/v1 Синтез речи
GET /api/tts/v1/voices Список голосов
GET, POST /api/account/tts-voices Список и создание пользовательских голосов; требуется portal-cookie
DELETE /api/account/tts-voices/{id} Удаление пользовательского голоса; требуется portal-cookie
POST /api/v1/audio/transcriptions Распознавание (OpenAI)
POST /api/v1/audio/speech Синтез речи (OpenAI)
GET /api/operations/{id} Статус операции
GET /api/operations Список доступных операций
POST /api/operations/{id}:cancel Отмена операции
POST /api/operations/{id}:purge Безвозвратная очистка response/error завершённой операции; Playground в приватном режиме запускает очистку автоматически
GET /docs Swagger UI (интерактивная документация OpenAPI)

Обработка ошибок

Ошибки возвращаются в формате JSON с полем detail:

{
  "detail": "Описание ошибки"
}
Код Значение
200 Запрос выполнен успешно
400 Некорректный запрос
401 Не аутентифицирован (отсутствует или неверный API-ключ)
402 Недостаточно кредитов
404 Ресурс не найден
409 Операция или ресурс находится в неподходящем состоянии
413 Превышен допустимый размер файла
422 Запрос не прошёл проверку схемы
500 Внутренняя ошибка сервиса
503 Бэкенд временно недоступен

См. также