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

Обновлено 10 июня 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