Асинхронное распознавание (HTTP и gRPC)
Подходит для распознавания многоканальных аудиозаписей. При работе стоит учитывать, что процесс асинхронного распознавания может быть дольше синхронного, поэтому этот тип подходит для случаев, когда длительность распознавания не важна.
Встроена функция оценки удовлетворенности клиента по Insight-модели CSI (Customer Satisfaction Index).
Максимальный размер аудио – 1 Гб.
Чтобы распознать длинное аудио:
Загрузите файл для распознавания по протоколу HTTP или gRPC в наше хранилище. В ответе придет идентификатор загруженного файла. Загруженный файл будет доступен в течение 72 часов, его нельзя скачать или изменить.
Создайте задачу на распознавание: в запросе передайте идентификатор файла и параметры распознавания. В ответе придет идентификатор задачи.
note
Необязательно создавать задачу сразу после загрузки файла, между шагами может быть промежуток в несколько часов.
Запросите статус задачи, чтобы узнать о ее завершении. Если задача находится в статусе NEW, т.е. еще не запустилась, ее можно отменить. Когда задача будет готова, вы получите идентификатор файла с результатом распознавания.
Скачайте файл с результатом по индентификатору. Файл будет доступен в течение 90 дней.
Описание API распознавания через HTTP
Загрузка файла на распознавание
Запрос
Чтобы загрузить файл для распознавания в облачное хранилище SmartSpeech, отправьте HTTP-запрос методом POST на следующий URL:
https://smartspeech.sber.ru/rest/v1/data:upload
Заголовки запроса
Наименование | Описание |
---|---|
Обязательное | Информация об аутентификации с помощью Access Token, переданная через OAuth 2.0
Пример |
Тело запроса
В теле запроса передается файл.
Пример запроса
Загрузка файла с компьютера:
curl -X POST \
-H "Authorization: Bearer {{token}}" \
--data-binary @./audio.pcm \
https://smartspeech.sber.ru/rest/v1/data:upload
Загрузка файла из интернета:
curl -fsSL -o - https://raw.githubusercontent.com/sberdevices/golos/master/examples/data/001ce26c07c20eaa0d666b824c6c6924.wav | \
curl -X POST \
-H "Authorization: Bearer {{token}}" \
--data-binary @- \
https://smartspeech.sber.ru/rest/v1/data:upload
Ответ
В случае успешного POST-запроса в ответ придет request_file_id
.
Заголовки ответа
Наименование | Описание |
---|---|
Обязательное | Уникальный ID запроса, генерируемый сервером ASCII строка, 36 символов
|
Обязательное для статуса 200 | Формат тела ответа сервиса
|
Формат ответа при успешном запросе
При успешном запросе придет HTTP-код 200.
Заголовки:
Content-Type: application/json; charset=utf-8
X-Request-ID: 2345200-abe8-4f60-90c8-0d43c5f6c0f6
Тело:
{
"status": 200,
"result": {
"request_file_id": "2345200-abe8-4f60-90c8-0d43c5f6c0f6"
}
}
Формат ответа при неуспешном запросе
Если запрос не выполнен, придет код ошибки с описанием в формате JSON.
Код | Описание |
---|---|
| Ошибка в параметрах запроса Пример |
| Не предоставлен токен для аутентификации Пример |
| Превышен максимальный размер входных данных Пример |
| Слишком много запросов Пример |
| Внутренняя ошибка сервиса Пример |
Создание задачи на асинхронное распознавание
Запрос
Отправьте HTTP-запрос методом POST на следующий URL:
https://smartspeech.sber.ru/rest/v1/speech:async_recognize
В запросе передайте идентификатор загруженного файла, а также параметры распознавания.
Параметры запроса
Наименование | Описание |
---|---|
|
Аудиокодек Возможные значения смотрите в разделе Доступные кодировки аудио |
|
Частота дискретизации Зависит от значения |
|
Международный код языка для распознавания речи На данный момент поддерживается только русский язык – ru-RU |
|
Фильтр обсценной лексики
|
|
Количество сообщаемых альтернативных гипотез распознанной речи Любое число от 0 и до 10, по умолчанию – 1 |
|
Имя акустической модели для распознавания речи Подробнее читайте в разделе Акустические модели |
|
Интервал ожидания речи пользователя Возможные значения от 2 до 20 секунд. По умолчанию – 7 секунд |
|
Определение максимальной длины высказывания до форсированного EOU Возможные значения – от 0,5 до 20 секунд. По умолчанию – 20 секунд |
|
Количество каналов в многоканальном аудио. Об ограничениях читайте в разделе Доступные кодировки аудио |
| Hints - составной тип, описан ниже |
|
Список слов или фраз, распознавание которых мы хотим усилить. Здесь можно перечислить слова, которые с высокой вероятностью будет произносить пользователь |
|
Модель коротких фраз, улучшающая распознавание отдельных букв и коротких слов
значение по умолчанию – false |
|
Настройка распознавания конца фразы (End of Utterance - eou). Такое распознавание будет ожидаться после конца фразы столько секунд, сколько установлено в этом параметре Возможные значения – от 0.5 до 5 секунд. По умолчанию распознавание конца фразы срабатывает после 1 секунды |
|
Оценка удовлетворенности клиента по аудио с использованием моделей Insights Единственное возможное значение — csi |
Пример запроса
curl -X POST \
-H "Authorization: Bearer {{token}}" \
-H "Content-Type: application/json" \
--data '
{
"options": {
"language": "ru-RU",
"model": "general",
"audio_encoding": "PCM_S16LE",
"sample_rate": 16000,
"hypotheses_count": 1,
"enable_profanity_filter": false,
"max_speech_timeout": "20s",
"channels_count": 2,
"no_speech_timeout": "7s",
"hints": {
"words": ["карту", "гуакамоле"],
"enable_letters": true,
"eou_timeout": "2s"
}
"insight_models": ["csi"]
},
"request_file_id": "file_id"
}' \
https://smartspeech.sber.ru/rest/v1/speech:async_recognize
Ответ
В ответе сервис вернет уникальный идентификатор и основные параметры задачи на распознавание.
Пример ответа:
Заголовки:
Content-Type: application/json; charset=utf-8
X-Request-ID: dafaf982-a32a-4e26-ae40-2bb9444906e1
Тело:
{
"status": 200,
"result": {
"id": "dafaf982-a32a-4e26-ae40-2bb9444906e1",
"created_at": "2021-07-15T17:35:17.182454861+03:00",
"updated_at": "2021-07-15T17:35:17.18245504+03:00",
"status": "NEW"
}
}
Получение статуса задачи
Отправьте HTTP-запрос методом GET на следующий URL:
https://smartspeech.sber.ru/rest/v1/task:get
В запросе передайте идентификатор задачи.
Пример запроса на curl:
curl \
-H "Authorization: Bearer {{token}}" \
"https://smartspeech.sber.ru/rest/v1/task:get?id={{task_id}}"
Если задача готова, в ответе сервис вернет статус DONE и идентификатор файла с результатом распознавания в параметре response_file_id
. Если в ответе придет статус ERROR, описание ошибки будет отображаться в параметре error
.
Пример ответа:
Заголовки:
Content-Type: application/json; charset=utf-8
X-Request-ID: dafaf982-a32a-4e26-ae40-2bb9444906e1
Тело:
{
"status": 200,
"result": {
"id": "dafaf982-a32a-4e26-ae40-2bb9444906e1",
"created_at": "2021-07-15T17:35:17.182454861+03:00",
"updated_at": "2021-07-15T17:35:57.18245504+03:00",
"status": "DONE",
"response_file_id": "2d45b5dc-73fe-40b1-9c89-0eea703036e5"
}
}
Пример ответа с ошибкой:
Заголовки:
Content-Type: application/json; charset=utf-8
X-Request-ID: dafaf982-a32a-4e26-ae40-2bb9444906e1
Тело:
{
"status": 200,
"result": {
"id": "dafaf982-a32a-4e26-ae40-2bb9444906e1",
"created_at": "2021-07-15T17:35:17.182454+03:00",
"updated_at": "2021-07-15T17:35:21.209015+03:00",
"status": "ERROR",
"error": "internal error"
}
}
Отмена задачи в статусе NEW
Если при проверке статуса сервис вернул значение NEW, задачу можно отменить.
Отправьте HTTP-запрос методом POST на следующий URL:
https://smartspeech.sber.ru/rest/v1/task:cancel
Пример запроса на curl:
curl -X POST \
-H "Authorization: Bearer {{token}}" \
"https: //smartspeech.sber.ru/rest/v1/task:cancel?id={{task_id}}"
В ответе сервис вернет статус CANCELED.
Пример ответа:
Заголовки:
Content-Type: application/json; charset=utf-8
X-Request-ID: dafaf982-a32a-4e26-ae40-2bb9444906e1
Тело:
{
"status": 200,
"result": {
"id": "dafaf982-a32a-4e26-ae40-2bb9444906e1",
"created_at": "2021-07-15T17:35:17.182454861+03:00",
"updated_at": "2021-07-15T17:35:57.18245504+03:00",
"status": "CANCELED"
}
}
Скачивание файла с результатом
Запрос
Отправьте HTTP-запрос методом GET на следующий URL:
https://smartspeech.sber.ru/rest/v1/data:download
Заголовки запроса
Наименование | Описание |
---|---|
Обязательное | Информация об аутентификации с помощью Access Token, переданная через OAuth 2.0
Пример |
Параметры запроса
Наименование | Описание |
Обязательное | Ключ для получения файла с результатами. Выдается в результате успешного выполнения задачи на распознавание ASCII строка, 36 символов Пример |
Пример запроса на curl:
curl \
-H "Authorization: Bearer {{token}}" \
"https://smartspeech.sber.ru/rest/v1/data:download?response_file_id={{response_file_id}}"
Ответ
Формат ответа при успешном запросе
В случае успешного GET-запроса в теле ответа возвращается содержимое файла.
Формат ответа при неуспешном запросе
Если запрос не выполнен, придет код ошибки с описанием в формате JSON.
Код | Описание |
---|---|
| Ошибка в параметрах запроса Пример |
| Не предоставлен токен для аутентификации Пример |
| Превышен максимальный размер входных данных Пример |
| Слишком много запросов Пример |
| Внутренняя ошибка сервиса Пример |
Описание API распознавания через gRPC
Запросы на распознавание передаются на адрес:
smartspeech.sber.ru
Создание приложения
Для работы с сервисом распознавания речи SmartSpeech создайте клиентское приложение. Вы можете использовать любой язык программирования, который есть в библиотеке для работы с gRPC.
При написании приложения используйте proto-файл из архива.
Подробную инструкцию по написанию клиентских приложений для gRPC с примерами вы найдёте в официальной документации gRPC (английский язык).
Загрузка файла для распознавания
При обращении по gRPC-протоколу клиентское приложение отправляет аудиофайл с помощью метода Upload. Аудиофайл отправляется в виде чанков в сообщении UploadRequest.file_chunk
типа bytes.
Сервис вернет сообщение UploadResponse с идентификатором загруженного файла в параметре request_file_id
.
Создание задачи на асинхронное распознавание
Клиентское приложение с помощью метода AsyncRecognize передает идентификатор загруженного файла, а также параметры распознавания. В ответе сервис вернет уникальный идентификатор задачи на распознавание.
Получение статуса задачи
Клиентское приложение передает идентификатор задачи на распознавание с помощью метода GetTask. Если задача готова, в ответе придет статус DONE и идентификатор файла с результатом распознавания в параметре response_file_id
. Если в ответе придет статус ERROR, описание ошибки будет отображаться в параметре error
.
Пример структуры Task для gRPC можно посмотреть в архиве.
Отмена задачи в статусе NEW
Если при проверке статуса сервис вернул значение NEW, задачу можно отменить. Клиентское приложение передает идентификатор задачи с помощью метода CancelTask. В ответе сервис вернет статус CANCELED.
Пример структуры Task для gRPC можно посмотреть в архиве.
Скачивание файла с результатом
Клиентское приложение передает идентификатор файла с результатом распознавания с помощью метода Download. Значение передается в параметре response_file_id
сообщения DownloadRequest
. Сервис вернет результат распознавания в виде чанков в сообщении DownloadResponse
.
Пример без Insight-моделей
С описанием параметров вы можете ознакомиться в разделе API потокового распознавания.
[
{
"results": [
{
"text": "раз два три",
"normalized_text": "1 2 3",
"start": "0.760s",
"end": "2s",
"word_alignments": [
{
"word": "раз",
"start": "0.760s",
"end": "0.880s"
},
{
"word": "два",
"start": "1.340s",
"end": "1.460s"
},
{
"word": "три",
"start": "1.880s",
"end": "2s"
}
]
}
],
"eou": true,
"emotions_result": {
"positive": 0.017408885,
"neutral": 0.7625851,
"negative": 0.22000594
},
"processed_audio_start": "0s",
"processed_audio_end": "2.447375104s",
"backend_info": {
"model_name": "general",
"model_version": "M-01.018.00-general-01",
"server_version": "01.017.00-04"
},
"channel": 0
},
{
"results": [
{
"text": "раз два три",
"normalized_text": "1 2 3",
"start": "0.760s",
"end": "2s",
"word_alignments": [
{
"word": "раз",
"start": "0.760s",
"end": "0.880s"
},
{
"word": "два",
"start": "1.340s",
"end": "1.460s"
},
{
"word": "три",
"start": "1.880s",
"end": "2s"
}
]
}
],
"eou": true,
"emotions_result": {
"positive": 0.018223174,
"neutral": 0.76795995,
"negative": 0.2138168
},
"processed_audio_start": "0s",
"processed_audio_end": "2.447375104s",
"backend_info": {
"model_name": "general",
"model_version": "M-01.018.00-general-01",
"server_version": "01.017.00-04"
},
"channel": 1
}
]
Пример с Insight-моделями
{
"insight_result": {
"csi": {
"positive": 0.6,
"negative": 0.4,
"prediction": 1
}
},
"result": [см. в примере результата без оценки CSI]
}
Сообщения об ошибках
Сервис SmartSpeech сообщает об ошибках стандартными gRPC-статусами. Ниже в таблице приведены некоторые коды и описание ошибок.
Код | Описание |
---|---|
|
Клиент неправильно заполнил параметры распознавания речи |
|
Клиенту недоступно API распознавания речи |
|
Клиент превысил квоту на распознавание речи |
|
Ошибка в работе сервиса распознавания речи |
|
Клиент не предоставил или предоставил истекший/невалидный токен в заголовке Authorization |
Описание ошибки для каждого сообщения указано в поле message.
Заметили ошибку?
Выделите текст и нажмите Ctrl
+ Enter
, чтобы сообщить нам о ней