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

Асинхронное распознавание — STT v3

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

Метод совместим с Yandex SpeechKit STT v3. Отправьте аудио, получите id операции и запросите результат, когда он будет готов.

Как это работает

sequenceDiagram
    participant C as Клиент
    participant API as API

    C->>API: POST /api/stt/v3/recognizeFile
    API-->>C: {"id": "abc-123", "done": false}

    loop Ожидание
        C->>API: GET /api/operations/abc-123
        API-->>C: {"id": "abc-123", "done": false}
    end

    C->>API: GET /api/operations/abc-123
    API-->>C: {"id": "abc-123", "done": true, "response": {...}}

    C->>API: GET /api/stt/v3/getRecognition?operationId=abc-123
    API-->>C: Конечный JSONL-поток событий
  1. Отправьте аудио — получите id операции.
  2. Периодически запрашивайте статус операции по id.
  3. Когда в ответе появится done: true, заберите итоговый агрегат из поля response.
  4. Если нужен совместимый поток StreamingResponse, вызовите getRecognition с тем же id.

HTTP-запрос

POST /api/stt/v3/recognizeFile

Запрос отправляется в формате application/json и требует аутентификации — заголовок Authorization: Api-Key <ключ> (см. Аутентификация).

Параметры запроса

Источник аудио

Укажите ровно один из двух параметров:

Параметр Тип Описание
content string Аудио в кодировке Base64
uri string Публичный HTTP(S)-URL для скачивания аудиофайла

uri не принимает локальные/приватные IP, userinfo и произвольные схемы. Редиректы и TLS проверяются на каждом переходе, а объём скачивания ограничен 500 МБ. Проверка источника и скачивание выполняются внутри фоновой операции, поэтому часть ошибок появится в Operation.error, а не в исходном ответе создания задачи.

Дополнительно на верхнем уровне запроса:

Параметр Тип По умолчанию Описание
includeVadSegments boolean false Запросить интервалы речи. Доступность и точность интервалов зависят от модели; при диаризации разметка соответствует speakerSegments. Для моделей без временной разметки поле может быть null
recognitionClassifier object — Классификаторы распознанной речи. Это основное расположение поля; устаревшее recognitionModel.recognitionClassifier пока принимается для обратной совместимости
speakerLabeling object — Настройки разметки спикеров в формате SpeechKit STT v3
speechAnalysis object — Детерминированная аналитика речи по таймстемпам: статистика спикеров, паузы, одновременная речь и перебивания
summarization object — LLM-суммаризация нормализованной транскрипции в текстовом или структурированном формате

Разметка спикеров (speakerLabeling)

Параметр Тип По умолчанию Описание
speakerLabeling string SPEAKER_LABELING_DISABLED SPEAKER_LABELING_ENABLED включает диаризацию, SPEAKER_LABELING_DISABLED выключает её
maxSpeakers integer — Расширение Speech Expert: максимальное число спикеров от 1 до 20. Gemini определяет спикеров автоматически и поддерживает значение не более 8; значение 1–8 не задаёт Google жёсткую цель

Стандартное поле speakerLabeling принимается в совместимом со SpeechKit формате. Поле maxSpeakers можно не передавать; оно является необязательным расширением Speech Expert.

Для gemini-3.5-transcribe включённый speakerLabeling использует диаризацию Google. Границы слов и метки спикеров сохраняются в совместимом ответе.

Для ElevenLabs-Scribe-v2, ElevenLabs-Scribe-v3 и ElevenLabs-Scribe-v2-Medical включённый speakerLabeling использует нативную диаризацию ElevenLabs без отдельной доплаты. Таймкоды слов возвращаются в final.alternatives[].words, а реплики спикеров — в speakerSegments.

Аналитика речи (speechAnalysis)

Параметр Тип По умолчанию Описание
enableSpeakerAnalysis boolean false Статистика длительности речи и тишины, темпа и реплик каждого спикера
enableConversationAnalysis boolean false Общая речь и тишина, одновременная речь и перебивания; результат появляется при наличии минимум двух спикеров или каналов
descriptiveStatisticsQuantiles number[] [] Квантили от 0 до 1, например [0.5, 0.9, 0.95]; применяются ко всем распределениям

Расчёт не использует LLM: он воспроизводимо строится по временным границам диаризованных реплик, VAD-сегментов или слов. Для многоканального звонка speakerTag совпадает с channelTag. Перебиванием считается начало реплики, пока другой спикер уже говорит; одновременный старт реплик перебиванием не считается.

Аналитика требует хотя бы одного фрагмента с ненулевой длительностью. Если выбранная модель не вернула word offsets и запрос не создал разметку диаризации/VAD, speakerAnalysis будет пустым, а conversationAnalysis — отсутствовать. Паузы спикера считаются внутри окна от его первой до последней реплики; общая тишина — внутри границ всего разговора.

Классификаторы (recognitionClassifier)

recognitionClassifier передаётся на верхнем уровне запроса, рядом с recognitionModel, speakerLabeling и speechAnalysis.

Параметр Тип Описание
classifiers[].classifier string Поддерживается negative — классификация негативной эмоциональной окраски DUSHA
classifiers[].triggers string[] Для офлайн-метода recognizeFile: ON_FINAL, ON_UTTERANCE. Триггер ON_PARTIAL не поддерживается

Устаревшее расположение recognitionModel.recognitionClassifier продолжает приниматься. Если в запросе присутствуют оба поля, верхнеуровневое recognitionClassifier имеет приоритет. В частности, пустой верхнеуровневый список classifiers отключает классификаторы из legacy-поля.

Если запрошен классификатор negative, результаты появляются и в совместимом агрегате response.classifiers, и как отдельные classifierUpdate в response.recognitionEvents. Возможные метки: angry, neutral, other, positive, sad.

Классификация выполняется один раз по всему файлу. Поэтому ON_FINAL и ON_UTTERANCE возвращают один и тот же результат на интервале от начала до конца файла; различается только windowType события. highlights всегда пуст. Неизвестные имена классификаторов игнорируются, а недоступность анализа эмоций не прерывает распознавание — массив классификаторов остаётся пустым. ON_PARTIAL для файлового метода завершается ошибкой и его не следует отправлять.

Суммаризация (summarization)

Схема запроса соответствует SpeechKit STT v3:

Параметр Тип По умолчанию Описание
modelUri string "" Допускается пустая строка или совместимый публичный идентификатор google/gemini-3.5-flash-lite-minimal; фактическую модель выбирает сервер
properties object[] — От 1 до 16 независимых инструкций; для каждой выполняется отдельный LLM-запрос
outputLanguage string locale распознавания или язык речи BCP-47 tag языка сгенерированных значений, например en-US; не меняет транскрипт
properties[].instruction string — Непустая инструкция длиной до 8000 символов; пробелы по краям удаляются
properties[].jsonObject boolean — При true запрос результата в виде JSON-объекта; false эквивалентен обычному текстовому ответу
properties[].jsonSchema object — Объект вида {"schema": {...}} с валидной JSON Schema результата размером до 65 536 байт UTF-8

В одном элементе properties можно указать не более одного формата ответа: jsonObject или jsonSchema. Допустимо не указывать ни один из них. Даже jsonObject: false считается явно указанным вариантом и не может сочетаться с jsonSchema. В jsonSchema разрешены только локальные $ref/$dynamicRef, начинающиеся с #; внешние ссылки отклоняются до создания операции.

{
  "summarization": {
    "modelUri": "google/gemini-3.5-flash-lite-minimal",
    "outputLanguage": "en-US",
    "properties": [
      {
        "instruction": "Верни причину обращения и итог разговора",
        "jsonSchema": {
          "schema": {
            "type": "object",
            "properties": {
              "reason": {"type": "string"},
              "outcome": {"type": "string"}
            },
            "required": ["reason", "outcome"]
          }
        }
      }
    ]
  }
}

Суммаризация выполняется после распознавания и всей финальной текстовой обработки. В LLM передаётся нормализованная транскрипция; при диаризации или нескольких каналах в ней сохраняются метки и порядок реплик. Клиент не может переключить модель через modelUri: другое непустое публичное значение отклоняется как невалидный запрос.

Язык результата

summarization.outputLanguage независимо задаёт язык всех сгенерированных значений. Если поле не передано, сохраняется прежнее поведение: выбранный recognitionModel.languageRestriction.languageCode используется как locale результата, а без него выбирается преобладающий язык исходной речи. Язык инструкции, имена полей и описания JSON Schema не переключают ответ на другой язык. В многоязычной записи имена, термины и цитаты сохраняются на языке оригинала; технические JSON-ключи остаются такими, как их задал клиент.

Для каждого элемента properties выполняется один независимый LLM-запрос. Порядок элементов в summarization.results совпадает с порядком инструкций, а каждый response всегда является строкой. Для jsonObject и jsonSchema эта строка содержит сериализованный JSON. contentUsage суммирует расход всех инструкций, только если провайдер вернул корректный usage для каждой из них; его поля inputTextTokens, completionTokens и totalTokens сериализуются строками, как protobuf int64. Для пустой транскрипции провайдер не вызывается: на каждую инструкцию возвращается пустая строка и нулевой contentUsage.

Пример структурированного результата (JSON Schema проверяется сервером, но совместимое поле response остаётся строкой):

{
  "summarization": {
    "results": [
      {
        "response": "{\"reason\":\"Delivery problem\",\"outcome\":\"The order was canceled\"}"
      }
    ],
    "contentUsage": {
      "inputTextTokens": "365",
      "completionTokens": "23",
      "totalTokens": "388"
    }
  }
}

Результат хранится в агрегированном response.summarization и одновременно добавляется последним session-level событием summarization в response.recognitionEvents/getRecognition. У него нет channelTag, в том числе для многоканального аудио: вся сессия суммаризируется один раз после объединения каналов.

Ошибка LLM, невалидный структурированный ответ или превышение лимита входа считаются ошибкой всей операции. Частичный успешный результат распознавания в этом случае не выдаётся как завершённая суммаризация. Отсутствующее поле или "summarization": null отключает функцию.

Модель распознавания (recognitionModel)

Для GigaAM v3 RNNT укажите recognitionModel.model: "GigaAM-v3-RNNT" и русский язык ru-RU. Модель выбирается явно и возвращает текст без нативных пословных таймкодов. Для потока тот же ID включает уточнение завершённых фраз через gRPC или WebSocket. Модель по умолчанию не меняется.

Параметр Тип По умолчанию Описание
model string SpeechExpert-STT-RU Файловая модель: SpeechExpert-STT-RU, SpeechExpert-STT-Heavy, SpeechExpert-STT-KK-Large, SpeechExpert-STT-TG-Large, SpeechExpert-STT-KY-Large, SpeechExpert-STT-HY-Large, SpeechExpert-STT-UZ-Large, Whisper-Kotib-UZ, Whisper-Callcenter-UZ, Uzinfocom-FastConformer-UZ, GigaAM-v3-RNNT, Mhery-RNNT, GigaAM-UZ-0.6B, Yandex-SpeechKit, GigaAM-Multilingual-Large-CTC, SpeechExpert-STT-UZ, Parakeet-EN, SpeechExpert-STT-EN, Whisper-Large-v3-Turbo, ElevenLabs-Scribe-v2, ElevenLabs-Scribe-v3, ElevenLabs-Scribe-v2-Medical, gpt-transcribe или gemini-3.5-transcribe

Для GPT Transcribe выберите recognitionModel.model: "gpt-transcribe" и один язык из ru-RU, en-US, kk-KZ, ky-KG, uz-UZ, tg-TJ, hy-AM. OpenAI определяет язык по аудио; выбранный код не ограничивает язык на стороне провайдера. Используйте готовый mono-файл без speakerLabeling и дополнительной LLM-коррекции. Пословные таймкоды и живой поток недоступны. Подготовленный mono WAV ограничен 25 МБ. Аудио передаётся OpenAI; в приватном режиме нужно согласие externalAiConsent=true. Списание — стоимость провайдера ×2; актуальная ставка и округление описаны в STT v1.

Для улучшенного узбекского распознавания выберите SpeechExpert-STT-UZ-Large и единственный язык uz-UZ. Передайте готовый mono-файл; модель возвращает текст и пофразовую разметку при доступном выравнивании, без диаризации и пословных таймкодов. При includeVadSegments=true границы фраз возвращаются в vadSegments; если надёжная разметка недоступна, возвращается полный текст без временных сегментов. Не включайте speakerLabeling, дополнительную коррекцию текста и audioRecovery. Живой поток недоступен. При распознавании этой моделью аудио и текст обрабатываются в контуре Speech Expert и не передаются внешним ASR- и LLM-провайдерам.

{
  "uri": "https://storage.example.com/uzbek-mono.wav",
  "includeVadSegments": true,
  "recognitionModel": {
    "model": "SpeechExpert-STT-UZ-Large",
    "languageRestriction": {"restrictionType": "WHITELIST", "languageCode": ["uz-UZ"]}
  }
}

Отдельно можно выбрать Whisper-Kotib-UZ, Whisper-Callcenter-UZ или Uzinfocom-FastConformer-UZ с тем же единственным языком uz-UZ. Это локальные файловые модели для mono без диаризации и точных таймкодов; живой поток и дополнительная LLM-коррекция не поддерживаются. Тарифы описаны в STT v1. Перевод, резюмирование и другие отдельно выбранные функции обработки готового текста имеют собственные условия передачи данных.

Для улучшенного казахского распознавания выберите SpeechExpert-STT-KK-Large и единственный язык kk-KZ. Передайте готовый mono-файл; результат содержит текст без диаризации и точных таймкодов. Не включайте speakerLabeling, дополнительную коррекцию текста и audioRecovery. Живой поток и уточнение финалов потока недоступны. Аудио обрабатывается с привлечением внешнего сервиса; в приватном режиме требуется согласие externalAiConsent=true. Тариф и условия округления приведены в STT v1.

{
  "uri": "https://storage.example.com/kazakh-mono.wav",
  "recognitionModel": {
    "model": "SpeechExpert-STT-KK-Large",
    "languageRestriction": {"restrictionType": "WHITELIST", "languageCode": ["kk-KZ"]}
  }
}

Для таджикского выберите SpeechExpert-STT-TG-Large и единственный язык tg-TJ. Модель принимает готовый mono-файл и возвращает текст без диаризации и точных таймкодов; живой поток и уточнение финалов потока недоступны. Не включайте speakerLabeling и дополнительную коррекцию текста.

{
  "uri": "https://storage.example.com/tajik-mono.wav",
  "recognitionModel": {
    "model": "SpeechExpert-STT-TG-Large",
    "languageRestriction": {"restrictionType": "WHITELIST", "languageCode": ["tg-TJ"]}
  }
}

Это отдельная файловая модель, параметр audioRecovery ей не нужен. Алиас SpeechExpert-STT-TJ-Large также принимается. Требования к внешней обработке и тариф приведены в STT v1.

Для кыргызского выберите SpeechExpert-STT-KY-Large и единственный язык ky-KG. Передайте готовый mono-файл; модель возвращает текст без диаризации и точных таймкодов. Не включайте speakerLabeling, дополнительную коррекцию текста и audioRecovery. Живой поток и уточнение финалов потока недоступны. Требования к внешней обработке и тариф приведены в STT v1.

{
  "uri": "https://storage.example.com/kyrgyz-mono.wav",
  "recognitionModel": {
    "model": "SpeechExpert-STT-KY-Large",
    "languageRestriction": {"restrictionType": "WHITELIST", "languageCode": ["ky-KG"]}
  }
}

Для улучшенного армянского распознавания выберите SpeechExpert-STT-HY-Large и единственный язык hy-AM. Передайте готовый mono-файл; результат — нормализованный армянский текст строчными буквами без пунктуации, без диаризации и точных таймкодов. Не включайте speakerLabeling, дополнительную коррекцию текста и audioRecovery. Живой поток и уточнение финалов потока недоступны. Требования к внешней обработке и тариф приведены в STT v1.

{
  "uri": "https://storage.example.com/armenian-mono.wav",
  "recognitionModel": {
    "model": "SpeechExpert-STT-HY-Large",
    "languageRestriction": {"restrictionType": "WHITELIST", "languageCode": ["hy-AM"]}
  }
}

Для локального армянского распознавания выберите recognitionModel.model: "Mhery-RNNT" и recognitionModel.languageRestriction.languageCode: ["hy-AM"]. Модель возвращает текст без точных пословных таймкодов и без автоматической нормализации написания, чисел и пунктуации. Укажите один армянский язык; BLACKLIST и список из нескольких языков не поддерживаются.

SpeechExpert Heavy — усиленное распознавание сложных и шумных записей. Передайте recognitionModel.model: "SpeechExpert-STT-Heavy" и язык ru-RU. Модель доступна только для офлайн-распознавания mono и возвращает текст без диаризации и точных таймкодов. Включённый speakerLabeling или многоканальный вход возвращают 400: это относится и к исходному stereo в аудиоконтейнере, даже если каналы дублируются. Для Heavy заранее подготовьте mono-файл; автоматическое сведение каналов этого маршрута не применяется.

Qwen3-ASR 1.7B временно отключена в API и кабинете. Актуальные доступные модели публикуются в GET /api/stt/capabilities.

Yandex STT выбирается через recognitionModel.model: "Yandex-SpeechKit" и ["ru-RU"]. Модель предназначена только для готовых файлов, не принимает speakerLabeling и возвращает нативные пословные таймкоды. Для Yandex подготовьте mono-файл; для raw PCM укажите rawAudio.audioChannelCount: "1". Раздельные каналы не поддерживаются и отклоняются до распознавания. Подтверждённые дублирующие каналы dual-mono автоматически сводятся в один. Живое распознавание и уточнение финалов потока для этой модели недоступны.

Для узбекского languageRestriction.languageCode: ["uz-UZ"] можно выбрать recognitionModel.model: "GigaAM-UZ-0.6B" или "GigaAM-Multilingual-Large-CTC". GigaAM UZ 0.6B — отдельная модель с нативной пунктуацией для готовых файлов; она не поддерживает speakerLabeling, живой поток и точные пословные таймкоды. Границы фрагментов оценочные.

Тарифы и округление длительности описаны в STT v1: Yandex — 17,073 кредита в минуту с округлением вверх до 15 секунд.

Для Scribe v3 укажите recognitionModel.model: "ElevenLabs-Scribe-v3" (также принимается алиас scribe_v3) и язык явно, например recognitionModel.languageRestriction.languageCode: ["hy-AM"]. Поддерживается курируемый набор 75 языков, включая русский, английский, казахский, кыргызский, узбекский, таджикский и армянский. Аудио передаётся ElevenLabs; в приватном режиме требуется externalAiConsent=true. Тариф — 1750 кредитов за час (около 29,17 кредита, или 1,17 ₽ за минуту), с округлением до начатой секунды и включённой нативной диаризацией. Модель предназначена для готовых файлов. Автоматическое определение языка lang=auto доступно через отдельный профиль Scribe v2 в STT v1.

ElevenLabs-Scribe-v2-Medical — вариант Scribe v2 для медицинской и клинической речи. Обе модели используют общий курируемый набор 75 языков, включая русский, английский, казахский, кыргызский, узбекский и таджикский; Medical передаёт провайдеру model_id=scribe_v2_medical и использует тот же тариф. По справочнику ElevenLabs Medical предназначена для файлового распознавания, а для живой речи предусмотрена отдельная ElevenLabs-Scribe-v2-Realtime. В нашем сервисе она доступна в gRPC STT v3 и WebSocket без дополнительного файлового уточнения; recognizeFile её не принимает.

Потоковые модели T-One, SpeechExpert-STT-KK-stream, SpeechExpert-STT-UZ-stream и SpeechExpert-STT-TG-stream доступны через gRPC и WebSocket, включая потоковую загрузку длинного файла. Для асинхронного файлового HTTP v3 выбирайте модель из таблицы выше. gRPC RecognizeStreaming использует отдельные session_options и поле recognition_model.model; для Realtime передайте "ElevenLabs-Scribe-v2-Realtime" или "scribe_v2_realtime".

Для узбекского файла используйте SpeechExpert-STT-UZ. Отдельный потоковый профиль SpeechExpert-STT-UZ-stream возвращает предварительный текст по мере речи и уточняет окончательный текст каждой завершённой фразы.

Для кыргызского ky-KG значение GigaAM-Multilingual-Large-CTC также доступно в gRPC, живом WebSocket и потоковой загрузке длинного файла. В потоке итог каждой фразы уточняется автоматически. Обычный файловый HTTP v3 по-прежнему распознаёт готовую запись с указанным значением модели; промежуточные результаты живой речи через getRecognition не передаются.

Язык (recognitionModel.languageRestriction)

Параметр По умолчанию Поведение
restrictionType LANGUAGE_RESTRICTION_TYPE_UNSPECIFIED Для GigaAM Multilingual WHITELIST требует ровно один код, а BLACKLIST отклоняется с HTTP 400; для остальных моделей сохраняется совместимое поведение
languageCode [] Для GigaAM v3 RNNT — только ru/ru-RU; для Mhery RNNT — только hy/hy-AM; для GigaAM Multilingual укажите один из ru-RU, kk-KZ, ky-KG; SpeechExpert-STT-UZ принимает uz/uz-UZ; Parakeet-EN и SpeechExpert-STT-EN — английский (en/en-US); публичный профиль Gemini принимает ru-RU, en-US, kk-KZ, ky-KG, uz-UZ, tg-TJ; файловые Scribe v2, Scribe v3 и Scribe v2 Medical принимают 75 языков курируемого набора. Без списка применяется серверный язык. У остальных моделей из непустого списка используется первый код

Это языковая подсказка, а не результат автоматического определения языка. Для GigaAM Multilingual alternatives[].languages остаётся пустым: выбранный код не выдаётся за результат language detection.

Для kk-KZ и ky-KG рекомендуется проверить качество GigaAM на своей акустике, акцентах и словаре. Таджикский tg-TJ этой моделью не поддерживается.

gemini-3.5-transcribe — внешняя мультиязычная модель Google. Она поддерживает переключение языков внутри записи; выбранный BCP-47 код передаётся как языковая подсказка, а не как выбор отдельной модели. STT v3 всегда запрашивает нативные таймстемпы слов, поэтому предел этого маршрута — 30 минут на запрос. Лимит 60 минут относится только к text-only OpenAI-совместимому маршруту без timestamps и диаризации. Word timestamps могут снижать точность распознавания. Потоковые WebSocket/gRPC-методы модель не поддерживает.

Формат аудио (recognitionModel.audioFormat)

audioFormat совместим с oneof SpeechKit v3: в нём должен быть указан ровно один объект — rawAudio или containerAudio. Если весь audioFormat опущен, сохраняется прежнее поведение: WAV определяется по заголовку, остальные байты считаются raw PCM. Поэтому для MP3 и OGG/Opus containerAudio нужно указывать явно.

Параметры rawAudio:

Параметр По умолчанию Описание
audioEncoding LINEAR16_PCM Кодирование аудио
sampleRateHertz 16000 Частота дискретизации
audioChannelCount 1 Количество каналов raw PCM. Каждый указанный канал распознаётся отдельно

Поддерживается от 1 до 32 каналов. Raw PCM должен содержать целые interleaved-кадры: число 16-битных сэмплов в payload кратно числу каналов, а каждый сэмпл имеет формат signed little-endian PCM16.

Для контейнерного аудио передаётся только тип; частота и количество каналов извлекаются из самого файла:

{
  "recognitionModel": {
    "audioFormat": {
      "containerAudio": {
        "containerAudioType": "OGG_OPUS"
      }
    }
  }
}

Поддерживаются WAV (целочисленный PCM и IEEE Float, wFormatTag=3), OGG_OPUS (именно Opus в OGG, не Vorbis) и MP3. Контейнер проверяется по фактическим байтам; исходное количество каналов сохраняется. Многоканальное аудио распознаётся поканально и возвращается в channelResults. Если явно включён speakerLabeling, каналы вместо этого сводятся в mono и проходят один общий режим диаризации.

Перед поканальным распознаванием двухканальный PCM анализируется по активным временным окнам. Если каналы имеют устойчивую высокую положительную корреляцию и стабильное соотношение уровней, запись считается dual-mono и сводится в один mono WAV. В этом случае ответ использует обычный final без channelResults. Раздельное stereo, противофаза, один тихий канал и частичное совпадение не схлопываются.

Для ElevenLabs-Scribe-v2, ElevenLabs-Scribe-v3 и ElevenLabs-Scribe-v2-Medical исходное аудио передаётся внешнему сервису одним запросом. Многоканальный результат преобразуется в channelResults; channel_index=0 становится channelTag="1". Поддерживается до пяти каналов. Нативные таймкоды слов сохраняются в альтернативе каждого канала.

Для обнаруженного dual-mono в ElevenLabs передаётся сведённая mono-запись, чтобы результат не содержал два одинаковых канала. Несовпадение containerAudioType с файлом или повреждённый контейнер завершает операцию с ошибкой 400. Пустой containerAudio, значение CONTAINER_AUDIO_TYPE_UNSPECIFIED, одновременные rawAudio и containerAudio отклоняются при валидации запроса (422).

Для gemini-3.5-transcribe аудио передаётся внешнему Google API. Нативные word timestamps преобразуются в final.alternatives[].words, а нативные метки спикеров — в speakerSegments и связанные события распознавания. Для многоканального входа сохраняется совместимый поканальный контракт STT v3.

Поддержка контейнеров на этом этапе относится к асинхронному HTTP API v3. Потоковый gRPC API по-прежнему принимает raw PCM chunks.

Нормализация текста (recognitionModel.textNormalization)

Параметр По умолчанию Описание
textNormalization TEXT_NORMALIZATION_DISABLED TEXT_NORMALIZATION_ENABLED или TEXT_NORMALIZATION_DISABLED
profanityFilter false Фильтр нецензурной лексики
literatureText false Литературный стиль текста
phoneFormattingMode PHONE_FORMATTING_MODE_DISABLED PHONE_FORMATTING_MODE_UNSPECIFIED включает форматирование телефонных номеров, PHONE_FORMATTING_MODE_DISABLED выключает его

Ответ

Для многоканального аудио стандартное поле final сохраняется. В final.alternatives[0].text тексты каналов соединяются в порядке каналов, а массив words объединяется и сортируется по startTimeMs. Дополнительно Speech Expert возвращает channelResults: один AlternativeUpdate на канал с номером канала в channelTag ("1", "2" и далее). Для одноканального аудио ответ остаётся стандартным, без channelResults.

Канонические события (recognitionEvents)

Завершённая операция дополнительно содержит response.recognitionEvents — упорядоченный список событий в форме StreamingResponse. Каждый элемент содержит общую оболочку:

  • sessionUuid — идентификатор сессии;
  • audioCursors — позиции обработанного аудио;
  • responseWallTimeMs — прошедшее время обработки операции на момент события, в миллисекундах;
  • channelTag — канал события, если он определён;
  • ровно одну полезную нагрузку события. recognizeFile создаёт final, finalRefinement, eouUpdate, classifierUpdate, speakerAnalysis, conversationAnalysis и summarization.

Для mono создаётся последовательность final → необязательный finalRefinement → eouUpdate. Для multichannel такая последовательность создаётся для каждого элемента channelResults; номер канала помещается в recognitionEvents[].channelTag (и сохраняется в самом AlternativeUpdate). Объединённый верхнеуровневый final остаётся агрегатом для обратной совместимости, но отдельное синтетическое событие для него не создаётся. После событий распознавания в список добавляются события классификаторов, аналитика каждого спикера и общая аналитика разговора. В multichannel-ответе classifierUpdate и speakerAnalysis также получают channelTag исходного канала; у общей conversationAnalysis канал не задаётся.

{
  "recognitionEvents": [
    {
      "sessionUuid": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "userRequestId": "operation-id"
      },
      "audioCursors": {
        "receivedDataMs": "10100",
        "resetTimeMs": "0",
        "partialTimeMs": "10100",
        "finalTimeMs": "10100",
        "finalIndex": "0",
        "eouTimeMs": "0"
      },
      "responseWallTimeMs": "12",
      "channelTag": "1",
      "final": {
        "channelTag": "1",
        "alternatives": [{"text": "Здравствуйте", "startTimeMs": "120", "endTimeMs": "980", "confidence": "0", "words": [], "languages": [{"languageCode": "ru-RU", "probability": "1"}]}]
      }
    }
  ]
}

Поля final, channelResults, vadSegments, speakerSegments, classifiers, speechAnalysis и summarization продолжают возвращаться как агрегаты. Клиенты могут мигрировать на recognitionEvents постепенно.

Для SpeechExpert-STT-RU, SpeechExpert-STT-EN и SpeechExpert-STT-UZ final.alternatives[].words содержит нативные startTimeMs/endTimeMs от начала исходного файла. Эти значения сохраняются и при includeVadSegments=true, и после текстовой нормализации: words описывают результат модели до финальной обработки, а text — итоговый обработанный текст. При разбиении длинного файла каждый чанк переводится в общую абсолютную шкалу. Текст vadSegments[] проходит ту же пунктуацию и нормализацию, что и итоговый final.alternatives[].text; временные границы VAD при этом не меняются.

Для GigaAM-Multilingual-Large-CTC нативные CTC-границы слов переводятся на абсолютную шкалу исходного файла. Границы альтернативы охватывают первое и последнее распознанные слова, а реальные паузы сохраняют разделение реплик.

При includeVadSegments=true поле vadSegments содержит распознанные реплики на той же абсолютной шкале. audioCursors.receivedDataMs, partialTimeMs, finalTimeMs и eouTimeMs отражают курсор всего исходного PCM, включая паузы, и не заменяют word timestamps. При включённой разметке спикеров speakerSegments описывает интервалы диаризации. Для записи без распознанной речи текст и words пусты, а audioCursors всё равно достигает длительности входного аудио.

Сервис возвращает объект операции:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2025-01-15T10:30:00.000000",
  "done": false,
  "response": null,
  "error": null
}

Дальнейший статус проверяйте методом GET /api/operations/{id} — подробности в разделе Операции.

Получение событий (getRecognition)

После того как GET /api/operations/{id} вернул done: true, канонический поток событий можно получить отдельным SpeechKit-совместимым методом:

GET /api/stt/v3/getRecognition?operationId=<UUID>

Метод принимает идентификатор как operationId или operation_id. Если переданы оба параметра, их значения должны совпадать. Ответ — конечная последовательность JSON-объектов, разделённых переводами строки; это не JSON-массив. Каждая непустая строка имеет форму {"result": <StreamingResponse>}; HTTP Content-Type при этом остаётся application/json.

curl --no-buffer \
  -H "Authorization: Api-Key $API_KEY" \
  "https://api.speech.example.com/api/stt/v3/getRecognition?operationId=$OPERATION_ID"

Пример JSONL-ответа для включённой нормализации (каждый объект расположен на отдельной строке):

{"result":{"sessionUuid":{"uuid":"550e8400-e29b-41d4-a716-446655440000","userRequestId":"operation-id"},"audioCursors":{"receivedDataMs":"980","resetTimeMs":"0","partialTimeMs":"980","finalTimeMs":"980","finalIndex":"0","eouTimeMs":"0"},"responseWallTimeMs":"12","final":{"alternatives":[{"words":[],"text":"здравствуйте иван","startTimeMs":"120","endTimeMs":"980","confidence":"0","languages":[{"languageCode":"ru-RU","probability":"1"}]}]}}}
{"result":{"sessionUuid":{"uuid":"550e8400-e29b-41d4-a716-446655440000","userRequestId":"operation-id"},"audioCursors":{"receivedDataMs":"980","resetTimeMs":"0","partialTimeMs":"980","finalTimeMs":"980","finalIndex":"0","eouTimeMs":"0"},"responseWallTimeMs":"12","finalRefinement":{"finalIndex":"0","normalizedText":{"alternatives":[{"words":[],"text":"Здравствуйте, Иван.","startTimeMs":"120","endTimeMs":"980","confidence":"0","languages":[{"languageCode":"ru-RU","probability":"1"}]}]}}}}
{"result":{"sessionUuid":{"uuid":"550e8400-e29b-41d4-a716-446655440000","userRequestId":"operation-id"},"audioCursors":{"receivedDataMs":"980","resetTimeMs":"0","partialTimeMs":"980","finalTimeMs":"980","finalIndex":"0","eouTimeMs":"980"},"responseWallTimeMs":"12","eouUpdate":{"timeMs":"980"}}}

Порядок событий фиксирован:

final (до локальной постобработки) → finalRefinement (опционально) → eouUpdate
→ classifierUpdate* → speakerAnalysis* → conversationAnalysis?
→ summarization?

Для multichannel первая цепочка повторяется для каждого канала, и только затем добавляются классификаторы и аналитика. finalRefinement создаётся, если запрошен хотя бы один режим финальной обработки: textNormalization, profanityFilter, literatureText или активный phoneFormattingMode. Событие создаётся и тогда, когда обработчик не изменил строку. Его normalizedText содержит обработанный текст, а words, языки и временные границы сохраняются от final до локальной постобработки.

Если запрошена суммаризация, её единственное session-level событие приходит последним, после аналитики. В то же время GET /api/operations/{id} возвращает итоговый обработанный агрегат в response.final, а текст до локальной постобработки доступен в событии recognitionEvents[].final/потоке getRecognition.

В снимках audioCursors у final и finalRefinement поле eouTimeMs равно "0"; конечное значение появляется начиная с события eouUpdate.

finalRefinement.finalIndex указывает на исходный final. Для многоканального аудио события следует связывать по паре (channelTag, finalIndex): индексы могут повторяться в разных каналах. Поток завершается обычным EOF; отдельное синтетическое событие statusCode: CLOSED не добавляется, поэтому клиенту нужно читать ответ до конца.

Для ранее сохранённой STT v3 операции без response.recognitionEvents метод строит доступные события из агрегированных полей. Текст до локальной постобработки в таком старом результате восстановить нельзя, поэтому синтетический finalRefinement не создаётся.

Ошибки метода:

Код Когда возникает
404 Операция не найдена, принадлежит другому владельцу или создана не методом STT v3 recognizeFile
409 Операция ещё не завершена (done: false)
422 Идентификатор не передан, превышает допустимую длину или два query-параметра не совпадают
код сохранённой ошибки / 500 Распознавание завершилось ошибкой; HTTP-код из диапазона 400–599 сохраняется, остальные ошибки возвращаются как 500

При включенной разметке обычный результат в final сохраняется, а реплики дополнительно возвращаются в speakerSegments:

{
  "final": {
    "alternatives": [
      {
        "text": "Здравствуйте Добрый день",
        "startTimeMs": "120",
        "endTimeMs": "2450"
      }
    ]
  },
  "speakerSegments": [
    {
      "speakerId": 1,
      "startTimeMs": "120",
      "endTimeMs": "980",
      "text": "Здравствуйте"
    },
    {
      "speakerId": 2,
      "startTimeMs": "1150",
      "endTimeMs": "2450",
      "text": "Добрый день"
    }
  ]
}

speakerSegments — расширение Speech Expert. Если разметка выключена или не указана, поле отсутствует, а поведение v3 остается прежним.

При включённом speechAnalysis в результате операции появляется одноимённый агрегированный блок. Целочисленные длительности и счётчики сериализуются строками, как int64 в protobuf JSON:

{
  "speechAnalysis": {
    "speakerAnalysis": [
      {
        "speakerTag": "1",
        "windowType": "TOTAL",
        "speechBoundaries": {"startTimeMs": "120", "endTimeMs": "8900"},
        "totalSpeechMs": "5410",
        "speechRatio": 0.6162,
        "totalSilenceMs": "3370",
        "silenceRatio": 0.3838,
        "wordsCount": "74",
        "lettersCount": "392",
        "utteranceCount": "9",
        "wordsPerSecond": {"min": 1.2, "max": 4.1, "mean": 2.7, "std": 0.8, "quantiles": []}
      }
    ],
    "conversationAnalysis": {
      "conversationBoundaries": {"startTimeMs": "120", "endTimeMs": "10100"},
      "totalSpeechDurationMs": "8140",
      "totalSpeechRatio": 0.8156,
      "totalSimultaneousSilenceDurationMs": "1840",
      "totalSimultaneousSilenceRatio": 0.1844,
      "totalSimultaneousSpeechDurationMs": "620",
      "totalSimultaneousSpeechRatio": 0.0621,
      "speakerInterrupts": [
        {
          "speakerTag": "2",
          "interruptsCount": "2",
          "interruptsDurationMs": "620",
          "interrupts": [
            {"startTimeMs": "1820", "endTimeMs": "2150"},
            {"startTimeMs": "7040", "endTimeMs": "7330"}
          ]
        }
      ]
    }
  }
}

Полные объекты также содержат распределения lettersPerSecond, wordsPerUtterance, lettersPerUtterance, utteranceDurationEstimation, simultaneousSilenceDurationEstimation и simultaneousSpeechDurationEstimation.

Примеры использования

AUDIO_BASE64=$(base64 -i audio.wav)

curl -X POST "https://api.speech.example.com/api/stt/v3/recognizeFile" \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"$AUDIO_BASE64\",
    \"recognitionModel\": {
      \"model\": \"SpeechExpert-STT-RU\"
    }
  }"
curl -X POST "https://api.speech.example.com/api/stt/v3/recognizeFile" \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://storage.example.com/audio.wav",
    "recognitionModel": {
      "model": "SpeechExpert-STT-RU"
    }
  }'
import requests
import base64
import time

BASE_URL = "https://api.speech.example.com"
HEADERS = {"Authorization": "Api-Key <ваш-ключ>"}

# 1. Отправляем файл
with open("audio.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(f"{BASE_URL}/api/stt/v3/recognizeFile", headers=HEADERS, json={
    "content": audio_b64,
    "recognitionModel": {
        "model": "SpeechExpert-STT-RU",
    },
})
operation = resp.json()
print(f"Операция создана: {operation['id']}")

# 2. Ждём результат
while not operation["done"]:
    time.sleep(2)
    resp = requests.get(f"{BASE_URL}/api/operations/{operation['id']}", headers=HEADERS)
    operation = resp.json()

# 3. Читаем результат
if operation.get("error"):
    print(f"Ошибка: {operation['error']['message']}")
else:
    alternative = operation["response"]["final"]["alternatives"][0]
    print(f"Текст: {alternative['text']}")

Полный пример запроса

{
  "content": "UklGRi4AAABXQVZFZm10IBAAAA...",
  "recognitionModel": {
    "model": "SpeechExpert-STT-RU",
    "audioFormat": {
      "containerAudio": {
        "containerAudioType": "WAV"
      }
    },
    "textNormalization": {
      "textNormalization": "TEXT_NORMALIZATION_ENABLED",
      "profanityFilter": false
    }
  },
  "recognitionClassifier": {
    "classifiers": [
      {
        "classifier": "negative",
        "triggers": ["ON_FINAL"]
      }
    ]
  },
  "speakerLabeling": {
    "speakerLabeling": "SPEAKER_LABELING_ENABLED",
    "maxSpeakers": 4
  },
  "speechAnalysis": {
    "enableSpeakerAnalysis": true,
    "enableConversationAnalysis": true,
    "descriptiveStatisticsQuantiles": [0.5, 0.9]
  },
  "summarization": {
    "modelUri": "google/gemini-3.5-flash-lite-minimal",
    "outputLanguage": "en-US",
    "properties": [
      {
        "instruction": "Верни причину обращения и итог разговора",
        "jsonSchema": {
          "schema": {
            "type": "object",
            "properties": {
              "reason": {"type": "string"},
              "outcome": {"type": "string"}
            },
            "required": ["reason", "outcome"]
          }
        }
      }
    ]
  }
}

Ограничения

Параметр Значение
Максимальный размер файла, скачиваемого по uri 500 МБ
Максимальная длительность Gemini в text-only OpenAI-маршруте без word timestamps и диаризации 60 минут
Максимальная длительность Gemini в STT v3 (word timestamps запрашиваются всегда) 30 минут
Количество каналов raw PCM от 1 до 32
Количество summarization.properties от 1 до 16
Длина summarization.properties[].instruction от 1 до 8000 символов после удаления пробелов по краям
Размер summarization.properties[].jsonSchema.schema до 65 536 байт UTF-8
Длина summarization.outputLanguage до 35 символов; требуется валидный BCP-47 tag
Длина нормализованной транскрипции для суммаризации до 500 000 символов

Ошибки

Код Когда возникает
422 Некорректный JSON или невалидные параметры схемы
401 Не аутентифицирован (отсутствует или неверный API-ключ)
503 Сервис суммаризации недоступен; операция не создаётся
500 Ошибка создания задачи

Проверка uri, загрузка, декодирование контейнера, проверка межканального выравнивания raw PCM и само распознавание происходят в фоне. Поэтому их ошибки возвращаются в Operation.error уже созданной задачи, обычно с HTTP-кодом 400, 413, 422 или 500, а не обязательно в ответе recognizeFile.

Ошибки уже созданной операции суммаризации также сохраняются в Operation.error: 413 при превышении лимита транскрипции, 502 при ошибке провайдера или невалидном структурированном ответе и 504 при таймауте провайдера.

См. также