API асинхронного распознавания речи (HTTP)
Асинхронное распознавание по протоколу HTTP проходит в несколько шагов:
- Загрузка файла для распознавания.
- Создание задачи на асинхронное распознавание.
- Проверка статуса задачи.
- Скачивание результата.
Заголовки запросов и ответов для всех шагов одинаковы:
Заголовки запроса
Заголовки ответа
Загрузка файла
Описание форматов аудиофайлов, которые можно загружать для распозначания речи, — в разделе Доступные форматы аудио.
Запрос
Чтобы загрузить файл для распознавания в облачное хранилище SaluteSpeech, отправьте HTTP-запрос методом POST на следующий URL:
https://smartspeech.sber.ru/rest/v1/data:upload
В теле запроса передается аудио-файл.
Пример запроса на загрузку файла с компьютера:
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-запроса в ответ придет идентификатор файла.
При успешном запросе придет HTTP-код 200.
Пример тела ответа:
{
"status": 200,
"result": {
"request_file_id": "2345200-abe8-4f60-90c8-0d43c5f6c0f6"
}
}
Если запрос не выполнен, придут код и описание ошибки в формате JSON.
Создание задачи
Запрос
Отправьте HTTP-запрос методом POST на следующий URL:
https://smartspeech.sber.ru/rest/v1/speech:async_recognize
В запросе передайте идентификатор загруженного файла, а также параметры распознавания.
Параметры запроса
Пример запроса
curl -X POST \
-H "Authorization: Bearer {{token}}" \
-H "Content-Type: application/json" \
--data '
{
"options": {
"language": "ru-RU",
"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"],
"speaker_separation_options": {
"enable": true,
"enable_only_main_speaker": false,
"count": 2
}
},
"request_file_id": "file_id"
}' \
https://smartspeech.sber.ru/rest/v1/speech:async_recognize
Ответ
В ответе сервис вернет уникальный идентификатор и основные параметры задачи на распознавание.
Пример тела ответа:
{
"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"
}
}
Если запрос не выполнен, придут код и описание ошибки в формате JSON.
Получение статуса задачи
Запрос
Отправьте HTTP-запрос методом GET на следующий URL:
https://smartspeech.sber.ru/rest/v1/task:get
В запросе передайте идентификатор задачи.
Пример запроса:
curl \
-H "Authorization: Bearer {{token}}" \
"https://smartspeech.sber.ru/rest/v1/task:get?id={{task_id}}"
Ответ
Если задача готова, в ответе сервис вернет статус DONE и идентификатор файла с результатом распознавания в параметре response_file_id. Если в ответе придет статус ERROR, описание ошибки будет отображаться в параметре error.
Пример тела ответа:
{
"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"
}
}
Пример тела ответа с ошибкой:
{
"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, задачу можно отменить.
Запрос
Отправьте HTTP-запрос методом POST на следующий URL:
https://smartspeech.sber.ru/rest/v1/task:cancel
Пример запроса:
curl -X POST \
-H "Authorization: Bearer {{token}}" \
"https: //smartspeech.sber.ru/rest/v1/task:cancel?id={{task_id}}"
Ответ
В ответе сервис вернет статус CANCELED.
Пример тела ответа:
{
"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
Параметры запроса
Пример запроса:
curl \
-H "Authorization: Bearer {{token}}" \
"https://smartspeech.sber.ru/rest/v1/data:download?response_file_id={{response_file_id}}"
Ответ
В случае успешного GET-запроса в теле ответа вернется содержимое файла.
Если запрос не выполнен, придут код и описание ошибки в формате JSON.
Коды ошибок
| Код | Описание |
|---|---|
400 | Ошибка в параметрах запроса. Пример {"status": 400, "message": "Id must not be empty"} |
401 | Не предоставлен токен для аутентификации. Пример {"status": 401, "message": "Unauthorized"} |
402 | Требуется оплатить сервис. Пример {"status": 402, "message": "Payment Required"} |
413 | Превышен максимальный размер входных данных. Пример {"status": 413, "message": "Payload too large"} |
429 | Слишком много запросов. Пример {"status": 429, "message": "Too Many Requests"} |
500 | Внутренняя ошибка сервиса. Пример {"status": 500, "message": "Internal Server Error"} |