API асинхронного синтеза речи (gRPC)

Обновлено 19 февраля 2025

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

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

Запросы к API передаются на адрес:

smartspeech.sber.ru

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

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

authorization

Bearer <Access token>

required

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

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

x-request-id

string

required

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

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

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

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

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

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

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

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

Протокол взаимодействия смотрите по ссылке.

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

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

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

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

request_file_id

string

required

Идентификатор загруженного файла

audio_encoding

string

required

Аудиокодек.
Единственное возможное значение — opus

voice

string

Код голоса для озвучивания.
Возможные значения смотрите в разделе Примеры голосов

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

service SmartSpeech {
  rpc AsyncSynthesize (AsyncSynthesisRequest) returns (smartspeech.task.v1.Task);
}
 
message AsyncSynthesisRequest {
  string request_file_id = 1;
  SynthesisRequest.AudioEncoding audio_encoding = 2;
  string voice = 3;
}

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

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

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

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

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

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

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

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

Протокол взаимодействия смотрите по ссылке.

Коды ошибок

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

Код	Описание
3	INVALID_ARGUMENT Клиент неправильно заполнил параметры запроса
5	NOT_FOUND Не определена модель из запроса или Файл не существует
7	PERMISSION_DENIED Клиенту недоступно API
8	RESOURCE_EXHAUSTED: payment required Клиент превысил квоту
8	RESOURCE_EXHAUSTED Слишком много запросов
13	INTERNAL Ошибка в работе сервиса
16	UNAUTHENTICATED Клиент не предоставил или предоставил истекший/невалидный токен в заголовке Authorization