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

Обновлено 4 июня 2024

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

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

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

smartspeech.sber.ru

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

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

authorization required

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

{

• "authorization": "string"

}

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

x-request-id required

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

{

• "x-request-id": "string"

}

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

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

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

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

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

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

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

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

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

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

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

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

request_file_id required	string Идентификатор загруженного файла
audio_encoding required	string Аудиокодек. Единственное возможное значение — opus
voice	string Код голоса для озвучивания. Возможные значения смотрите в разделе Примеры голосов

{

• "request_file_id": "string",
• "audio_encoding": "string",
• "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