Связаться с намиПодключиться

API v2 асинхронного распознавания

Статья создана
Обновлена 4 апреля 2025 г.

Важно

Функциональность доступна только в регионе Россия.

Для работы с API v2 понадобятся:

Подробнее о предварительной работе см. в разделе Как асинхронно распознать предзаписанное аудио.

Важно

Асинхронно распознать аудиофайлы можно только от имени сервисного аккаунта. Не используйте для этого другие аккаунты в Yandex Cloud.

Сервис асинхронного распознавания для API v2 располагается по адресу: transcribe.api.cloud.yandex.net/speech/stt/v2/longRunningRecognize

Отправить файл на распознавание

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

Структура тела запроса:

{
 "config": {
  "specification": {
   "languageCode": "string",
   "model": "string",
   "profanityFilter": boolean,
   "literature_text": boolean,
   "audioEncoding": "string",
   "sampleRateHertz": integer,
   "audioChannelCount": integer,
   "rawResults": boolean
  }
 },
 "audio": {
  "uri": "string"
 }
}

Параметр

Описание

config

object
Поле с настройками распознавания.

config.
specification

object
Настройки распознавания.

config.
specification.
languageCode

string
Язык речи в аудиозаписи для распознавания.
Значение по умолчанию — ru-RU  — русский язык.

config.
specification.
model

string
Языковая модель для распознавания речи.
Значение параметра по умолчанию: general.
Выбор модели влияет на стоимость использования.

config.
specification.
profanityFilter

boolean
Фильтр ненормативной лексики.
Допустимые значения:

  • true — замаскировать ненормативную лексику звездочками в результатах распознавания.
  • false (по умолчанию) — не маскировать ненормативную лексику.

config.
specification.
literature_text

boolean
Включает режим нормализации.

config.
specification.
audioEncoding

string
Формат передаваемого аудио.
Допустимые значения:

config.
specification.
sampleRateHertz

integer (int64)
Частота дискретизации передаваемого аудио.
Этот параметр обязателен, если значение format равно LINEAR16_PCM. Допустимые значения:

  • 48000 (по умолчанию) — частота дискретизации 48 кГц;
  • 16000 — частота дискретизации 16 кГц;
  • 8000 — частота дискретизации 8 кГц.

config.
specification.
audioChannelCount

integer (int64)
Количество каналов для аудиофайлов в формате LPCM. По умолчанию используется значение 1.
Не используйте это поле для аудиофайлов в формате OggOpus и MP3. Информация о количестве каналов уже содержится в этих файлах.

config.
specification.
rawResults

boolean
Флаг, указывающий, как писать числа.
Допустимые значения:

  • true — писать прописью.
  • false (по умолчанию) — писать цифрами.

audio.
uri

string
URI аудиофайла для распознавания. Поддерживаются только ссылки на файлы, которые хранятся в Yandex Object Storage.

Ответ

Если запрос был составлен правильно, сервис возвращает объект Operation, в котором содержится идентификатор операции распознавания (id):

{
 "done": false,
 "id": "e03sup6d5h1q********",
 "createdAt": "2019-04-21T22:49:29Z",
 "createdBy": "ajes08feato8********",
 "modifiedAt": "2019-04-21T22:49:29Z"
}

Используйте полученный идентификатор на следующем шаге.

Получить результаты распознавания

Чтобы проверить статус операции и получить результат распознавания, отправьте запрос по адресу: operation.api.cloud.yandex.net.

Проверяйте результаты распознавания, используя полученный идентификатор. Количество запросов на проверку результатов ограничено, 1 минута одноканального аудио распознается примерно за 10 секунд.

Важно

Результаты распознавания хранятся на сервере 3 суток. После этого вы не сможете запросить результаты распознавания, используя полученный идентификатор.

Path-параметры

Параметр Описание
operationId Идентификатор операции, полученный при отправке запроса на распознавание.

Ответ

В ответе на запрос возвращается объект Operation. Пример ответа:

{
 "done": true,
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.ai.stt.v2.LongRunningRecognitionResponse",
  "chunks": [
   {
    "alternatives": [
     {
      "words": [
       {
        "startTime": "0.879999999s",
        "endTime": "1.159999992s",
        "word": "при",
        "confidence": 1
       },
       {
        "startTime": "1.219999995s",
        "endTime": "1.539999988s",
        "word": "написании",
        "confidence": 1
       },
       ...
      ],
      "text": "при написании хоббита толкин обращался к мотивам скандинавской мифологии древней английской поэмы беовульф",
      "confidence": 1
     }
    ],
    "channelTag": "1"
   },
   ...
  ]
 },
 "id": "e03sup6d5h1q********",
 "createdAt": "2019-04-21T22:49:29Z",
 "createdBy": "ajes08feato8********",
 "modifiedAt": "2019-04-21T22:49:36Z"
}

Параметр

Описание

done

boolean
Содержит значение true, когда распознавание закончено.

response

object
Результаты асинхронного распознавания речи.

response.
@type

string
Тип ответа на запрос.

response.
chunks

array
Массив с результатами распознавания.
Если распознать речь в переданном файле не удастся, в ответе может отсутствовать массив с результатами.

response.
chunks.
alternatives

array
Массив с вариантами распознанного текста.

response.
chunks.
alternatives.
words

array
Массив с распознанными словами и информацией о них.

response.
chunks.
alternatives.
words.
startTime

string
Время начала слова в аудиозаписи. Возможна погрешность в пределах 1–2 секунд.

response.
chunks.
alternatives.
words.
endTime

string
Время окончания слова в аудиозаписи. Возможна погрешность в пределах 1–2 секунд.

response.
chunks.
alternatives.
words.
word

string
Распознанное слово. Распознанные числа пишутся прописью, например не 12, а двенадцать.

response.
chunks.
alternatives.
words.
confidence

integer (int64)
Поле не поддерживается, не используйте его.

response.
chunks.
alternatives.
text

string
Распознанный текст целиком. По умолчанию числа пишутся цифрами. Чтобы весь текст был прописью, укажите true в параметре config.specification.rawResult.

response.
chunks.
alternatives.
confidence

integer (int64)
Поле не поддерживается, не используйте его.

response.
chunks.
channelTag

string
Аудиоканал, для которого выполнено распознавание.

id

string
Идентификатор операции. Генерируется на стороне сервиса.

createdAt

google.protobuf.Timestamp
Время запуска операции. Указывается в формате RFC3339 (Timestamps).

createdBy

string
Идентификатор пользователя, запустившего операцию.

modifiedAt

google.protobuf.Timestamp
Время последнего изменения ресурса. Указывается в формате RFC3339 (Timestamps).

Подробнее о формате и кодах ответов см. на странице Коды ответов на запросы.

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

Предыдущая
API потокового распознавания
Следующая
Overview