ym88659208ym87991671
HTTP API асинхронного распознавание речи сервиса SaluteSpeech | Документация для разработчиков

API асинхронного распознавания речи (HTTP)

Обновлено 1 декабря 2023

Асинхронное распознавание по протоколу HTTP проходит в несколько шагов:

  1. Загрузка файла для распознавания.
  2. Создание задачи на асинхронное распознавание.
  3. Проверка статуса задачи.
  4. Скачивание результата.

Заголовки запросов и ответов для всех шагов одинаковы:

Заголовки запроса

Authorization
required
string <Bearer <Access token>>

Информация об аутентификации, переданная через OAuth 2.0.
Пример: Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw

{
  • "Authorization": "string"
}

Заголовки ответа

X-Request-ID
required
string

Уникальный ID запроса, генерируемый сервером. 36 символов.
Пример: 22345200-abe8-4f60-90c8-0d43c5f6c0f6

{
  • "X-Request-ID": "string"
}

Загрузка файла

Описание форматов аудиофайлов, которые можно загружать для распозначания речи, — в разделе Доступные форматы аудио.

Запрос

Чтобы загрузить файл для распознавания в облачное хранилище 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

В запросе передайте идентификатор загруженного файла, а также параметры распознавания.

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

audio_encoding
enum (AudioEncoding)

Аудиокодек.
Возможные значения смотрите в разделе Доступные форматы аудио

sample_rate
int32

Частота дискретизации.
Зависит от значения audio_encoding, подробнее читайте в разделе Доступные форматы аудио

language
string

Язык для распознавания речи.
Возможные значения:

  • ru-RU — русский. Значение по умолчанию.
  • en-US — английский.
  • kk-KZ — казахский. Доступно по отдельной заявке, напишите на почту SaluteSpeech@sberbank.ru
enable_profanity_filter
boolean

Фильтр обсценной лексики.
Возможные значения: true и false. Значение по умолчанию — false

hypotheses_count
int32

Количество сообщаемых альтернативных гипотез распознанной речи.
Любое число от 0 до 10. Значение по умолчанию — 1

no_speech_timeout
Duration

Интервал ожидания речи пользователя.
Любое число от 2 до 20.
По умолчанию – 7 секунд

max_speech_timeout
Duration

Определение максимальной длины высказывания до форсированного EOU.
Любое число от 0,5 до 20.
По умолчанию – 20 секунд

channels_count
int32

Количество каналов в многоканальном аудио.
Об ограничениях читайте в разделе Доступные форматы аудио

Hints
array (составной тип, см. ниже — Hints)

Хинты

Hints.words
repeated string

Список слов или фраз, распознавание которых мы хотим усилить.
Здесь можно перечислить слова, которые с высокой вероятностью будет произносить пользователь

Hints.enable_letters
boolean

Модель коротких фраз, улучшающая распознавание отдельных букв и коротких слов.
Возможные значения: true и false. Значение по умолчанию — false

Hints.eou_timeout
Duration

Настройка распознавания конца фразы (End of Utterance — eou). Такое распознавание будет ожидаться после конца фразы столько секунд, сколько установлено в этом параметре.
Возможные значения от 0.5 до 5 секунд. По умолчанию распознавание конца фразы срабатывает после 1 секунды

insight_models
repeated string

Оценка удовлетворенности клиента по аудио с использованием моделей Insights.
Работает только для двухканальных аудио.
Возможные значения:

  • csi;
  • call_features;
  • csi, call_features.

Подробнее читайте в разделе Insights модели

speaker_separation_options
array (составной тип, см. ниже — speaker_separation_options)

Параметры разделения спикеров для фрагментов одновременной речи

speaker_separation_options.enable
boolean

Включение функции разделения спикеров.
Возможные значения: true и false. Значение по умолчанию — false

speaker_separation_options.enable_only_main_speaker
boolean

Возвращение только главного спикера. Главный находится по max(main_speaker_confidence).
Возможные значения: true и false. Значение по умолчанию — false

speaker_separation_options.count
int32

Максимальное число спикеров. Единственное возможное значение — 2

{
  • "audio_encoding": null,
  • "sample_rate": null,
  • "language": "string",
  • "enable_profanity_filter": true,
  • "hypotheses_count": null,
  • "no_speech_timeout": null,
  • "max_speech_timeout": null,
  • "channels_count": null,
  • "Hints": null,
  • "Hints.words": null,
  • "Hints.enable_letters": true,
  • "Hints.eou_timeout": null,
  • "insight_models": null,
  • "speaker_separation_options": null,
  • "speaker_separation_options.enable": true,
  • "speaker_separation_options.enable_only_main_speaker": true,
  • "speaker_separation_options.count": null
}

Пример запроса

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

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

request_file_id
required
string

Ключ для получения файла с результатами. 36 символов.
Выдается в результате успешного выполнения задачи на распознавание.
Пример: 22345200-abe8-4f60-90c8-0d43c5f6c0f6

{
  • "request_file_id": "string"
}

Пример запроса:

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"}
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.