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

Обновлено 20 октября 2023

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

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

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

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

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 eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw" \
--data-binary @./text.txt \
https://smartspeech.sber.ru/rest/v1/data:upload

Пример запроса на загрузку файла из интернета:

curl -fsSL -o - https://raw.githubusercontent.com/sberdevices/golos/master/examples/data/001ce26c07c20eaa0d666b824c6c6924.txt | \
curl -X POST \
-H "Authorization: Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw" \
--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/text:async_synthesize

В запросе передайте идентификатор загруженного файла, а также параметры синтеза.

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

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

{

• "request_file_id": "string",
• "audio_encoding": "string",
• "voice": "string"

}

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

curl -X POST \
-H "Authorization: Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw" \
-d "{ \"audio_encoding\": \"opus\", \"voice\": \"Ost_24000\", \"request_file_id\": \"2345200-abe8-4f60-90c8-0d43c5f6c0f6\"}" \
https://smartspeech.sber.ru/rest/v1/text:async_synthesize

Ответ

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

Пример тела ответа:

{
    "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 eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw" \
"https://smartspeech.sber.ru/rest/v1/task:get?id=22345200-abe8-4f60-90c8-0d43c5f6c0f6"

Ответ

Если задача готова, в ответе сервис вернет статус 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"
    }
}

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

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

Если при проверке статуса сервис вернул значение NEW, задачу можно отменить.

Запрос

Отправьте HTTP-запрос методом POST на следующий URL:

https://smartspeech.sber.ru/rest/v1/task:cancel

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

curl -X POST \
-H "Authorization: Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw" \
"https: //smartspeech.sber.ru/rest/v1/task:cancel?id=22345200-abe8-4f60-90c8-0d43c5f6c0f6"

Ответ

В ответе вернется описание задачи со статусом 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 eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw" \
"https://smartspeech.sber.ru/rest/v1/data:download?response_file_id=22345200-abe8-4f60-90c8-0d43c5f6c0f6"

Ответ

В случае успешного GET-запроса в теле ответа вернется содержимое файла.

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

Коды ошибок

Код	Описание
400	Ошибка в параметрах запроса. Пример {"status": 400, "message": "Id must not be empty"}
401	Не предоставлен токен для аутентификации. Пример {"status": 401, "message": "Unauthorized"}
402	Требуется оплатить сервис. Пример {"status": 402, "message": "Payment Required"}
422	Ошибка при загрузке файла, например, файл слишком маленький. Пример {"status": 422, "message": "too small file, must be not less than 400 bytes"}
429	Слишком много запросов. Пример {"status": 429, "message": "Too Many Requests"}
500	Внутренняя ошибка сервиса. Пример {"status": 500, "message": "Internal Server Error"}