ym88659208ym87991671
API синтеза речи | Документация для разработчиков
Skip to main content

API синтеза речи

Обновлено 12 сентября 2022

Технология синтеза речи основана на нейронных сетях.

Для синтеза речи мы используем HTTP и gRPC протоколы.

Описание API синтеза через HTTP

Чтобы синтезировать речь, отправьте POST-запрос с параметрами синтеза и токеном, а также текстом для синтеза в теле запроса. Текст может быть в формате UTF8 или в виде SSML-разметки. Максимальный размер тела запроса — 4000 символов, включая пробелы и SSML-разметку.

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

Запрос

Отправьте запрос на адрес:

https://smartspeech.sber.ru/rest/v1/text:synthesize

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

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

Authorization

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

Информация об аутентификации, переданная через OAuth 2.0

Bearer <Access token>

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

Content-Type

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

Формат данных, передаваемых в теле запроса

ASCII строка.

Возможные значения:

  • application/text — текст в теле запроса передается в формате UTF8, например: Привет из 1984!
  • application/ssml — текст в теле запроса передается в формате SSML-разметки, например: <speak>За'мок на замке</speak>

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

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

format

ASCII строка

Формат синтезируемого аудио — любое значение из форматов аудио: wav16, pcm16, opus.

Значение по умолчанию wav16

voice

ASCII строка

Код голоса. Первая часть кода означает диктора, вторая - частоту дискретизации аудио

Модели с частотой 8000 Гц предназначены для использования в телефонии

Вы можете выбрать голос из раздела Примеры голосов для синтеза или использовать уникальный брендированный голос с помощью сервиса YourVoice.

Описание format

ЗначениеОписание формата

wav16

Возвращается WAV PCM 16bit LE signed, с заголовком. Частота дискретизации будет взята из параметра voice. В заголовке в поле длины синтеза стоит 0xFFFF, т.к. в момент форматирования заголовка невозможно знать длину синтезируемого звука. Стоит обратить внимание на то, что один фрейм звука — 16 бит, однако HTTP не гарантирует, что будет прочитано четное количество байт на каждый чанк, это следует учитывать при имплементации клиента

pcm16

Возвращается WAV PCM 16bit LE signed, без заголовка. Частота дискретизации будет взята из параметра voice. Стоит обратить внимание на то, что один фрейм звука — 16 бит, однако HTTP не гарантирует, что будет прочитано четное количество байт на каждый чанк, это следует учитывать при имплементации клиента

opus

Возвращается opus в контейнере ogg. Используется variable bitrate. Качество звука будет почти таким же, как и при audio/x-wav или audio/x-pcm, но в несколько раз меньшим по объему

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

curl -H "Authorization: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIn0..2EpRX7W33f8Bn7eL.uXPQt0QXDFPNKaC6uADyF24hiiYxVkdQI0G1AXV3YHaTyFWYnVbeIbw_aR8No8eiZaUbzlwT05HvUcKp.6df0vRM3DcDZmxWfwYcVUA" -H "Content-Type: application/text" --data-binary "Текст для синтеза" "https://smartspeech.sber.ru/rest/v1/text:synthesize?format=opus&voice=May_24000" > out.opus

Ответ

Тело HTTP-ответа содержит бинарное представление синтезированного звука в запрошенном формате, если запрос обработан успешно (код ответа 200).

Вам не нужно ждать полной обработки всего аудиопотока, вы получаете заголовки ответа почти сразу в течение секунды, и далее начинают приходить бинарные данные в потоковом режиме. Для потоковой передачи аудио в теле ответа используется Transfer-Encoding: chunked (см. RFC).

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

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

X-Request-ID

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

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

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

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

Content-Type

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

MIME аудио-формата синтезируемого аудио

ASCII строка, любое значение из ["audio/x-wav", "audio/x-pcm;bit=16;rate=<частота дискретизации>", "audio/ogg;codecs=opus"]

audio/x-pcm;bit=16;rate=8000

В случае ошибки заголовок Content-Type имеет формат "application/json".

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

При успешном запросе вы получаете HTTP-код 200.

Значение параметра formatОписание формата

wav16

audio/x-wav

pcm16

audio/x-pcm; bit=16; rate=<частота дискретизации>

opus

audio/ogg; codecs=opus

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

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

КодОписание

400

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

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

401

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

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

429

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

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

500

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

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

Описание API синтеза через gRPC

Помимо HTTP-протокола для синтеза речи мы используем gRPC протокол. Подробнее о нем можно прочитать в официальной документации. Запросы на синтез через gRPC передаются на адрес:

smartspeech.sber.ru

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

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

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

Передача параметров синтеза

При обращении по gRPC-протоколу с запросом синтеза речи клиентское приложение использует метод Synthesis. В сообщении клиент должен отправить опции синтеза в сообщении типа SynthesisRequest. Параметры этого сообщения описаны ниже в таблице.

ПараметрОписание

audio_encoding

enum (AudioEncoding)

Аудиокодек:

  • pcm16_se (16-битный PCM-поток с одним аудио-каналом, закодированный знаковыми целыми числами)
  • opus (ogg-поток с аудиокодеком opus внутри)
  • wav16, возвращается WAV PCM 16bit LE signed, с заголовком. Частота дискретизации берется из параметра voice

По умолчанию wav16

text

string

Текст для синтеза

Текст или SSML-разметка с текстом

content-type

ASCII строка

Формат данных, передаваемых в теле запроса

Одно из "text" или "ssml", по умолчанию "text"

voice

ASCII строка

Код голоса. Первая часть кода означает диктора, вторая - частоту дискретизации аудио

Модели с частотой 8000 Гц предназначены для использования в телефонии

Вы можете выбрать голос из раздела Примеры голосов для синтеза или использовать уникальный брендированный голос с помощью сервиса YourVoice.

Получение ответа

Клиент передает текст на вход в составе сообщения SynthesisRequest. Тело ответа в поле data содержит бинарное представление синтезированного звука в запрошенном формате, если запрос обработан успешно. Сервис в ответ передает клиенту сообщения SynthesisResponse.

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

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

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

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

X-Request-ID

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

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

Содержимое ответа

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

data

bytes

Чанки аудио в заданном формате

audio_duration

google.protobuf.Duration

Общая длительность сгенерированного в рамках запроса звука до текущего чанка

Кодировка данных при успешном запросе

При успешном запросы вы получаете в поле data аудио чанки в заданном формате.

Значение параметра dataОписание формата

wav16

audio/x-wav

pcm16

audio/x-pcm; bit=16; rate=<частота дискретизации>

opus

audio/ogg; codecs=opus

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

Сервис SaluteSpeech сообщает об ошибках стандартными gRPC-статусами, про которые можно подробно прочесть в официальной документации. Ниже в таблице приведены некоторые коды и Описание ошибок.

КодОписание

3

INVALID_ARGUMENT

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

7

PERMISSION_DENIED

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

9

RESOURCE_EXHAUSTED

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

13

INTERNAL

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

16

UNAUTHENTICATED

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

Для каждого из сообщений подробное описание произошедшей ошибки указывается в поле message.

Примеры клиентского приложения

Чтобы посмотреть пример клиентского приложения на Python, скачайте архив.

Примеры голосов для синтеза

Вы можете выбрать для синтеза один или несколько голосов из списка ниже или использовать уникальный брендированный голос с помощью сервиса YourVoice.

note

Через API не предоставляются голоса ассистентов

Прослушайте примеры доступных голосов перед выбором модели для синтеза.

Пример голосаКод голосовой модели
Наталья (24 кГц)

Nec_24000
Наталья (8 кГц)

Nec_8000
Борис (24 кГц)

Bys_24000
Борис (8 кГц)

Bys_8000
Марфа (24 кГц)

May_24000
Марфа (8 кГц)

May_8000
Тарас (24 кГц)

Tur_24000
Тарас (8 кГц)

Tur_8000
Александра (24 кГц)

Ost_24000
Александра (8 кГц)

Ost_8000
Сергей (24 кГц)

Pon_24000
Сергей (8 кГц)

Pon_8000
Kira (24 кГц) — синтез английской речи

Kin_24000
Kira (8 кГц) — синтез английской речи

Kin_8000

SSML-разметка

Улучшить синтез можно при помощи SSML-разметки. Если вы используете SSML-разметку, то в заголовке запроса на синтез Content-Type должно быть значение application/ssml. Сам текст с разметкой размещается в теле запроса. Подробно о SSML-разметке читайте в разделе Разметка синтеза речи.

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

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