ЗарегистрироватьсяВойти
SmartSpeech/API распознавания речи/

Асинхронное распознавание (HTTP и gRPC)

Подходит для распознавания многоканальных аудиозаписей. При работе стоит учитывать, что процесс асинхронного распознавания может быть дольше синхронного, поэтому этот тип подходит для случаев, когда длительность распознавания не важна.

Максимальный размер аудио – 1 Гб.

Чтобы распознать длинное аудио:

  1. Передайте файл для распознавания по протоколу HTTP или gRPC. В ответе придет идентификатор загруженного файла. Загруженный файл будет доступен в течение 72 часов, его нельзя скачать или изменить.

  2. Создайте задачу на распознавание: в запросе передайте идентификатор файла и параметры распознавания. В ответе придет идентификатор задачи.

    Необязательно создавать задачу сразу после загрузки файла, между шагами может быть промежуток в несколько часов.
  3. Запросите статус задачи, чтобы узнать о ее завершении. Если задача находится в статусе NEW, т.е. еще не запустилась, ее можно отменить. Когда задача будет готова, вы получите идентификатор файла с результатом распознавания.
  4. Скачайте файл с результатом по индентификатору. Файл будет доступен в течение 90 дней.

Описание API распознавания через HTTP

Чтобы загрузить файл для распознавания отправьте HTTP-запрос методом POST на следующий URL:

https://smartspeech.sber.ru/rest/v1/data:upload

Запрос

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

Наименование Описание

Authorization

Обязательное

Информация об аутентификации с помощью Access Token, переданная через OAuth 2.0

Bearer Access Token

Пример Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw

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

В теле запроса передается файл.

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

curl -X POST \
-H "Authorization: Bearer {{token}}" \
--data-binary @./audio.pcm https://smartspeech.sber.ru/rest/v1/data:upload

Ответ

В случае успешного POST-запроса в ответ придет request_file_id.

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

Наименование Описание

X-Request-ID

Обязательное

Уникальный ID запроса, генерируемый сервером

ASCII строка, 36 символов

22345200-abe8-4f60-90c8-0d43c5f6c0f6

Content-Type

Обязательное для статуса 200

Формат тела ответа сервиса

application/json

Формат ответа при успешном запросе

При успешном запросе придет 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.

Код Описание

400

Ошибка в параметрах запроса

Пример {"status": 400, "message": "<Описание ошибки входящих параметров>"}

401

Не предоставлен токен для аутентификации

Пример {"status": 401, "message": "Unauthorized"}

413

Превышен максимальный размер входных данных

Пример {"status": 413, "message": "Payload too large"}

429

Слишком много запросов

Пример {"status": 429, "message": "Too Many Requests"}

500

Внутренняя ошибка сервиса

Пример {"status": 500, "message": "Internal Server Error"|<описание ошибки ASR>"}

Создание задачи на асинхронное распознавание

Отправьте 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

enable_profanity_filter

boolean

Фильтр обсценной лексики

true/false, значение по умолчанию – false

hypotheses_count

int32

Количество сообщаемых альтернативных гипотез распознанной речи

Любое число от 0 и до 10, по умолчанию – 1

model

string

Имя языковой модели для распознавания речи

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

no_speech_timeout

Duration

Интервал ожидания речи пользователя

Возможные значения от 2 до 20 секунд.

По умолчанию – 7 секунд

max_speech_timeout

Duration

Определение максимальной длины высказывания до форсированного EOU

Возможные значения – от 0,5 до 20 секунд.

По умолчанию – 20 секунд

channels_count

int32

Количество каналов в многоканальном аудио.

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

Hints

Hints - составной тип, описан ниже

Hints.words

repeated string

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

Hints.enable_letters

boolean

Модель коротких фраз, улучшающая распознавание отдельных букв и коротких слов

true/false,

значение по умолчанию – false

Hints.eou_timeout

Duration

Настройка распознавания конца фразы (End of Utterance - eou). Такое распознавание будет ожидаться после конца фразы столько секунд, сколько установлено в этом параметре

Возможные значения – от 0.5 до 5 секунд.

По умолчанию распознавание конца фразы срабатывает после 1 секунды

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

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"
    }
  },
  "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

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

Наименование Описание

Authorization

Обязательное

Информация об аутентификации с помощью Access Token, переданная через OAuth 2.0

Bearer Access Token

Пример Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw

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

Наименование Описание

response_file_id

Обязательное

Ключ для получения файла с результатами. Выдается в результате успешного выполнения задачи на распознавание

ASCII строка, 36 символов

Пример Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw

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

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": "<Описание ошибки входящих параметров>"}

401

Не предоставлен токен для аутентификации

Пример {"status": 401, "message": "Unauthorized"}

413

Превышен максимальный размер входных данных

Пример {"status": 413, "message": "Payload too large"}

429

Слишком много запросов

Пример {"status": 429, "message": "Too Many Requests"}

500

Внутренняя ошибка сервиса

Пример {"status": 500, "message": "Internal Server Error"|<описание ошибки ASR>"}

Описание API распознавания через gRPC

Запросы на распознавание передаются на адрес:

smartspeech.sber.ru

Создание приложения

Для работы с сервисом распознавания речи SmartSpeech создайте клиентское приложение. Вы можете использовать любой язык программирования, который есть в библиотеке для работы с gRPC.

При написании приложения используйте proto-файл с нашей страницы на GitHub.

Подробную инструкцию по написанию клиентских приложений для gRPC с примерами вы найдёте в официальной документации gRPC.

Загрузка файла для распознавания

При обращении по gRPC-протоколу клиентское приложение отправляет аудиофайл с помощью метода Upload. Аудиофайл отправляется в виде чанков в сообщении UploadRequest.file_chunk типа bytes.

Сервис вернет сообщение UploadResponse с идентификатором загруженного файла в параметре request_file_id.

Создание задачи на асинхронное распознавание

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

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

Клиентское приложение передает идентификатор задачи на распознавание с помощью метода GetTask. Если задача готова, в ответе придет статус DONE и идентификатор файла с результатом распознавания в параметре response_file_id. Если в ответе придет статус ERROR, описание ошибки будет отображаться в параметре error.

Пример структуры Task для gRPC можно посмотреть на GitHub.

Отмена задачи в статусе NEW

Если при проверке статуса сервис вернул значение NEW, задачу можно отменить. Клиентское приложение передает идентификатор задачи с помощью метода CancelTask. В ответе сервис вернет статус CANCELED.

Пример структуры Task для gRPC можно посмотреть на GitHub.

Скачивание файла с результатом

Клиентское приложение передает идентификатор файла с результатом распознавания с помощью метода Download. Значение передается в параметре response_file_id сообщения DownloadRequest. Сервис вернет результат распознавания в виде чанков в сообщении DownloadResponse.

Сообщения об ошибках

Сервис SmartSpeech сообщает об ошибках стандартными gRPC-статусами. Ниже в таблице приведены некоторые коды и описание ошибок.

Код Описание

3

INVALID_ARGUMENT

Клиент неправильно заполнил параметры распознавания речи

7

PERMISSION_DENIED

Клиенту недоступно API распознавания речи

9

RESOURCE_EXHAUSTED

Клиент превысил квоту на распознавание речи

13

INTERNAL

Ошибка в работе сервиса распознавания речи

16

UNAUTHENTICATED

Клиент не предоставил или предоставил истекший/невалидный токен в заголовке Authorization

Описание ошибки для каждого сообщения указано в поле message.

Пример результата асинхронного распознавания

С описанием параметров вы можете ознакомиться в разделе 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
  }
]

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней

Потоковое (gRPC)