[Документация Yandex Cloud](../../../index.md) > [speechkit](../../index.md) > Справочники API > Распознавание > API v2 > API асинхронного распознавания
# API v2 асинхронного распознавания
{% note warning %}
Функциональность доступна только в [регионе Россия](../../../overview/concepts/region.md).
{% endnote %}
Для работы с API v2 понадобятся:
* [Бакет Yandex Object Storage](../../../storage/operations/buckets/create.md), в который вы загружаете аудиофайл для распознавания.
* [Сервисный аккаунт](../../../iam/operations/sa/create.md) с ролями `ai.speechkit-stt.user` и `storage.uploader`, которые нужны для работы со SpeechKit и Object Storage.
* [IAM-токен](../../../iam/operations/iam-token/create-for-sa.md) или [API-ключ](../../../iam/operations/authentication/manage-api-keys.md#create-api-key) для аутентификации.
Подробнее о предварительной работе смотрите в разделе [Как асинхронно распознать предзаписанное аудио](../transcribation.md#async-recognition).
{% note warning %}
Асинхронно распознать аудиофайлы можно только от имени сервисного аккаунта. Не используйте для этого [другие аккаунты в Yandex Cloud](../../../iam/concepts/users/accounts.md).
{% endnote %}
Сервис асинхронного распознавания для API v2 располагается по адресу: `transcribe.api.cloud.yandex.net/speech/stt/v2/longRunningRecognize`
## Отправить файл на распознавание {#sendfile}
### Параметры в теле запроса {#sendfile-params}
Структура тела запроса:
```json
{
"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**
[Язык речи](../models.md#languages) в аудиозаписи для распознавания.
Значение по умолчанию — `ru-RU` — русский язык. ||
|| config.
specification.
model | **string**
[Языковая модель](../models.md#tags) для распознавания речи.
Значение параметра по умолчанию: `general`.
Выбор модели влияет на [стоимость использования](../../pricing.md#rules-stt-long). ||
|| config.
specification.
profanityFilter | **boolean**
Фильтр ненормативной лексики.
Допустимые значения:- `true` — замаскировать ненормативную лексику звездочками в результатах распознавания.
- `false` (по умолчанию) — не маскировать ненормативную лексику.
||
|| config.
specification.
literature_text | **boolean**
Включает [режим нормализации](../normalization.md). ||
|| config.
specification.
audioEncoding | **string**
[Формат](../../formats.md) передаваемого аудио.
Допустимые значения:- `LINEAR16_PCM` — [LPCM без WAV-заголовка](../../formats.md#lpcm).
- `OGG_OPUS` (по умолчанию) — формат [Ogg](../../formats.md#oggopus) с кодеком OPUS.
- `MP3` — формат [MP3](../../formats.md#MP3).
||
|| config.
specification.
sampleRateHertz | **integer** (int64)
Частота дискретизации передаваемого аудио.
Этот параметр обязателен, если значение `format` равно `LINEAR16_PCM`. Допустимые значения:- `48000` (по умолчанию) — частота дискретизации 48 кГц;
- `16000` — частота дискретизации 16 кГц;
- `8000` — частота дискретизации 8 кГц.
||
|| config.
specification.
audioChannelCount | **integer** (int64)
Количество каналов для аудиофайлов в [формате LPCM](../../formats.md#lpcm). По умолчанию используется значение `1`.
Не используйте это поле для аудиофайлов в формате [OggOpus](../../formats.md#oggopus) и [MP3](../../formats.md#MP3). Информация о количестве каналов уже содержится в этих файлах. ||
|| config.
specification.
rawResults | **boolean**
Флаг, указывающий, как писать числа.Допустимые значения:- `true` — писать прописью.
- `false` (по умолчанию) — писать цифрами.
||
|| audio.
uri | **string**
URI аудиофайла для распознавания. Поддерживаются только ссылки на файлы, которые хранятся в [Yandex Object Storage](../../../storage/index.md). ||
|#
### Ответ {#sendfile-response}
Если запрос был составлен правильно, сервис возвращает [объект Operation](../../../api-design-guide/concepts/operation.md), в котором содержится идентификатор операции распознавания (`id`):
```json
{
"done": false,
"id": "e03sup6d5h1q********",
"createdAt": "2019-04-21T22:49:29Z",
"createdBy": "ajes08feato8********",
"modifiedAt": "2019-04-21T22:49:29Z"
}
```
Используйте полученный идентификатор на следующем шаге.
## Получить результаты распознавания {#get-result}
Чтобы проверить статус операции и получить результат распознавания, отправьте запрос по адресу: `operation.api.cloud.yandex.net`.
Проверяйте результаты распознавания, используя полученный идентификатор. Количество запросов на проверку результатов [ограничено](../../concepts/limits.md), 1 минута одноканального аудио распознается примерно за 10 секунд.
{% note warning %}
Результаты распознавания хранятся на сервере 3 суток. После этого вы не сможете запросить результаты распознавания, используя полученный идентификатор.
{% endnote %}
### Path-параметры {#get-result-params}
Параметр | Описание
----- | -----
operationId | Идентификатор операции, полученный при отправке запроса на распознавание.
### Ответ {#get-result-response}
В ответе на запрос возвращается [объект Operation](../../../api-design-guide/concepts/operation.md). Пример ответа:
```json
{
"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](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/timestamp.proto)
Время запуска операции. Указывается в формате [RFC3339 (Timestamps)](https://www.ietf.org/rfc/rfc3339.txt). ||
|| createdBy | **string**
Идентификатор пользователя, запустившего операцию. ||
|| modifiedAt | [google.protobuf.Timestamp](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/timestamp.proto)
Время последнего изменения ресурса. Указывается в формате [RFC3339 (Timestamps)](https://www.ietf.org/rfc/rfc3339.txt).
|#
Подробнее о формате и кодах ответов смотрите на странице [Коды ответов на запросы](../../concepts/response.md).
## Примеры использования {#examples}
* [Асинхронное распознавание аудиофайлов в формате LPCM в API v2](transcribation-lpcm.md).
* [Асинхронное распознавание аудиофайлов в формате OggOpus в API v2](transcribation-ogg.md).
* [Регулярное асинхронное распознавание аудиофайлов из Yandex Object Storage](batch-transcribation.md).