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

Обзор Speech-Expert API

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

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

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

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

Языки файлового распознавания

Локальный профиль GigaAM распознаёт готовые аудио- и видеофайлы на четырёх языках. ElevenLabs Scribe v2 поддерживает их, английский и таджикский:

Язык Locale STT v1/v3 Совместимые файловые модели Живой WebSocket/gRPC
Русский ru-RU GigaAM-Multilingual-Large-CTC, ElevenLabs-Scribe-v2 и другие совместимые модели да
Английский en-US ElevenLabs-Scribe-v2, Whisper-Large-v3-Turbo нет, используйте файл
Казахский kk-KZ GigaAM-Multilingual-Large-CTC, ElevenLabs-Scribe-v2 нет, используйте файл
Кыргызский ky-KG GigaAM-Multilingual-Large-CTC, ElevenLabs-Scribe-v2 нет, используйте файл
Узбекский uz-UZ GigaAM-Multilingual-Large-CTC, ElevenLabs-Scribe-v2 нет, используйте файл
Таджикский tg-TJ ElevenLabs-Scribe-v2 нет, используйте файл

В Playground язык выбирается перед моделью. В STT v1 передавайте и lang, и совместимую модель: GigaAM принимает только ru-RU, kk-KZ, ky-KG, uz-UZ, а ElevenLabs-Scribe-v2 также доступна для en-US и tg-TJ. Автоматического выбора модели по одному locale нет. Готовую расшифровку можно использовать для резюме и исследовательского отчёта. По умолчанию результат формируется на преобладающем языке записи, но для саммаризации можно независимо выбрать BCP-47 язык результата. Полный перевод транскрипта выполняется отдельным LLM-методом, не меняя исходный текст и его таймкоды.

Многоязычность ASR не переносится автоматически на классификацию эмоций. Эмоциональная динамика DUSHA включается параметром 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 + операции
Живой поток WebSocket Микрофон в браузере, mono PCM16 16 кГц и простой JSON WebSocket
Живой поток gRPC Телефония, protobuf, mono или многоканальный interleaved PCM gRPC
OpenAI-совместимый файловый стрим Целый файл загружается одним запросом, результат выдаётся как SSE HTTP + SSE

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

Способ Когда использовать Протокол
TTS Studio Длинная озвучка по фрагментам, версии дублей, свой голос и сборка WAV Веб-интерфейс
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 настройкой PUBLIC_API_ALLOW_ANONYMOUS=true; для production рекомендуется сохранять аутентификацию включённой.

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

Схемы Api-Key и Bearer

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

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

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

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

Ограничения

Параметр Значение
Максимальный размер multipart-загрузки аудио (STT v1, OpenAI Audio и сохранение записи) 200 МБ
Максимальный размер файла, скачиваемого по 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 завершённой операции; private Playground вызывает её автоматически
GET /docs Swagger UI (интерактивная документация OpenAPI)

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

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

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

См. также