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

Обновлено 24 января 2024

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

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

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

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

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-файл.

Если запрос не выполнен, придут код и описание ошибки в формате JSON.

Параметры ответа

results	array (составной тип, см. ниже — Results) Список гипотез распознавания речи. Гипотезы отсортированы по убыванию вероятности
Results.text	string Не нормализованный результат распознавания (например, сто двадцать три)
Results.normalized_text	string Нормализованный результат распознавания (например, 123)
Results.start	string Время от начала аудиозаписи до начала данной гипотезы в ней
Results.end	string Время от начала аудиозаписи до конца данной гипотезы в ней
Results.word_alignments	array (составной тип, см. ниже — WordAlignments) Время начала и окончания каждого слова
Results.WordAlignments.word	string Слово
Results.WordAlignments.start	string Время от начала аудиозаписи до начала произнесения слова
Results.WordAlignments.end	string Время от начала аудиозаписи до конца произнесения слова
eou	boolean Признак окончания распознанного предложения. Если `true`, то данный результат распознавания можно считать финальным. Если `false`, то возможно уточнение распознавания в следующих сообщениях
emotions_result	array (составной тип, см. ниже — EmotionsResult) Список эмоций в речи. Значения эмоциональной окраски речи приходят в виде коэффициентов в диапазоне от 0 до 1, где 1 — наиболее вероятная эмоция ответа, а 0 — наименее вероятная
EmotionsResult.positive	float Вероятность позитивной эмоциональной окраски речи — диапазон от 0 до 1
EmotionsResult.neutral	float Вероятность нейтральной эмоциональной окраски речи — диапазон от 0 до 1
EmotionsResult.negative	float Вероятность негативной эмоциональной окраски речи — диапазон от 0 до 1
processed_audio_start	string Время начала обработанного аудио
processed_audio_end	string Время конца обработанного аудио
backend_info	array (составной тип, см. ниже — BackendInfo) Модель ASR
BackendInfo.model_name	string Название модели
BackendInfo.model_version	string Версия модели
BackendInfo.server_version	string Версия сервера
channel	int32 Номер канала в двухканальных аудио. Для Insights надо, чтоб оператор был 0, а клиент — 1
speaker_info	array (составной тип, см. ниже — SpeakerInfo) Параметры разделения спикеров
SpeakerInfo.speaker_id	int32 Идентификатор результата распознавания: –1 — результат с речью обоих спикеров, 1 — результат с речью одного спикера, 2 — результат с речью другого спикера
SpeakerInfo.main_speaker_confidence	float Маркер главного спикера
eou_reason	string Причина окончания чанка. Возможные значения: `UNSPECIFIED` — нет чанка. `ORGANIC` — чанк закончился. `NO_SPEECH_TIMEOUT` — в чанке не было речи в течение времени, указанного в параметре `no_speech_timeout`. `MAX_SPEECH_TIMEOUT` — речь в чанке шла непрерывно в течение времени, указанного в параметре `max_speech_timeout`
insight_result	array (составной тип, см. ниже — InsightResult) Результаты анализа Insights модели
InsightResult.csi	array (составной тип, см. ниже — Csi) Результаты анализа модели CSI
InsightResult.Csi.positive	float Вероятность позитивной эмоциональной окраски речи — диапазон от 0 до 1
InsightResult.Csi.negative	float Вероятность негативной эмоциональной окраски речи — диапазон от 0 до 1
InsightResult.Csi.prediction	int32 Предсказанная эмоция
InsightResult.call_features	array (составной тип) Результаты анализа модели call_features. Описание параметров — в разделах Статистика по одному каналу и Сравнительная статистика

{"results": null,
"Results.text": "string",
"Results.normalized_text": "string",
"Results.start": "string",
"Results.end": "string",
"Results.word_alignments": null,
"Results.WordAlignments.word": "string",
"Results.WordAlignments.start": "string",
"Results.WordAlignments.end": "string",
"eou": true,
"emotions_result": null,
"EmotionsResult.positive": null,
"EmotionsResult.neutral": null,
"EmotionsResult.negative": null,
"processed_audio_start": "string",
"processed_audio_end": "string",
"backend_info": null,
"BackendInfo.model_name": "string",
"BackendInfo.model_version": "string",
"BackendInfo.server_version": "string",
"channel": null,
"speaker_info": null,
"SpeakerInfo.speaker_id": null,
"SpeakerInfo.main_speaker_confidence": null,
"eou_reason": "string",
"insight_result": null,
"InsightResult.csi": null,
"InsightResult.Csi.positive": null,
"InsightResult.Csi.negative": null,
"InsightResult.Csi.prediction": null,
"InsightResult.call_features": null
}

Примеры ответа

Стандартный ответ
Разделение спикеров
Insight-модели

[
    {
        "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,
        "speaker_info": {
            "speaker_id": -1,
            "main_speaker_confidence": 1
        },
        "eou_reason": "ORGANIC",
        "insight": ""
    },
]

[
  {
    "results": [
      {
        "text": "один два",
        "normalized_text": "1 2",
        "start": "0.320s",
        "end": "0.960s",
        "word_alignments": [
          {
            "word": "один",
            "start": "0.320s",
            "end": "0.519999968s"
          },
          {
            "word": "два",
            "start": "0.640s",
            "end": "0.960s"
          }
        ]
      }
    ],
    "eou": false,
    "emotions_result": {
      "positive": 0.22309092,
      "neutral": 0.39286476,
      "negative": 0.38404432
    },
    "processed_audio_start": "0s",
    "processed_audio_end": "2.444875008s",
    "backend_info": {
      "model_name": "general",
      "model_version": "M-02.002.00-general-01",
      "server_version": "02.004.00-rh8-trt-02"
    },
    "channel": 0,
    "speaker_info": {
      "speaker_id": 2,
      "main_speaker_confidence": 0.31004992
    }
  },
  {
    "results": [
      {
        "text": "один два четыре пять шесть",
        "normalized_text": "1, 3, 4, 5 6.",
        "start": "0.320s",
        "end": "1.880s",
        "word_alignments": [
          {
            "word": "один",
            "start": "0.320s",
            "end": "0.500s"
          },
          {
            "word": "два",
            "start": "0.780s",
            "end": "0.880s"
          },
          {
            "word": "четыре",
            "start": "1.160s",
            "end": "1.380s"
          },
          {
            "word": "пять",
            "start": "1.480s",
            "end": "1.620s"
          },
          {
            "word": "шесть",
            "start": "1.700s",
            "end": "1.880s"
          }
        ]
      }
    ],
    "eou": false,
    "emotions_result": {
      "positive": 0.0006413624,
      "neutral": 0.9987526,
      "negative": 0.000606051
    },
    "processed_audio_start": "0s",
    "processed_audio_end": "2.444875008s",
    "backend_info": {
      "model_name": "general",
      "model_version": "M-02.002.00-general-01",
      "server_version": "02.004.00-rh8-trt-02"
    },
    "channel": 0,
    "speaker_info": {
      "speaker_id": -1,
      "main_speaker_confidence": 0.31374687
    }
  },
  {
    "results": [
      {
        "text": "четыре пять шесть",
        "normalized_text": "4, 5 6.",
        "start": "1.140s",
        "end": "1.900s",
        "word_alignments": [
          {
            "word": "четыре",
            "start": "1.140s",
            "end": "1.400s"
          },
          {
            "word": "пять",
            "start": "1.480s",
            "end": "1.620s"
          },
          {
            "word": "шесть",
            "start": "1.680s",
            "end": "1.900s"
          }
        ]
      }
    ],
    "eou": true,
    "emotions_result": {
      "positive": 0.11293165,
      "neutral": 0.6017238,
      "negative": 0.28534454
    },
    "processed_audio_start": "0s",
    "processed_audio_end": "2.444875008s",
    "backend_info": {
      "model_name": "general",
      "model_version": "M-02.002.00-general-01",
      "server_version": "02.004.00-rh8-trt-02"
    },
    "channel": 0,
    "speaker_info": {
      "speaker_id": 1,
      "main_speaker_confidence": 0.3762032
    }
  }
]

{
  "insight_result": {
    "csi": {
      "positive": 0.6,
      "negative": 0.4,
      "prediction": 1
    }
  },
  "result": [см. в примере результата без оценки CSI]
}

Коды ошибок

Код	Описание
`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"}`

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

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

Запрос﻿

Ответ﻿

Создание задачи﻿

Запрос﻿

Ответ﻿

Получение статуса задачи﻿

Запрос﻿

Ответ﻿

Отмена задачи﻿

Запрос﻿

Ответ﻿

Скачивание результата﻿

Запрос﻿

Ответ﻿

Параметры ответа﻿

Примеры ответа﻿

Коды ошибок﻿

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

Запрос

Ответ

Создание задачи

Запрос

Ответ

Получение статуса задачи

Запрос

Ответ

Отмена задачи

Запрос

Ответ

Скачивание результата

Запрос

Ответ

Параметры ответа

Примеры ответа

Коды ошибок