Синтез речи

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

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

POST HTTP-запрос отправляется по адресу:

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

Запрос

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

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

Authorization

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

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

Bearer JWE токен

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

Content-Type

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

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

ASCII строка, одно из ["application/text","application/ssml"]

Пример application/text

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

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

format

Формат синтезируемого аудио

ASCII строка, любое значение из форматов аудио ["wav16", "pcm16", "opus"]

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

voice

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

ASCII строка, выбор модели для синтеза, любое значение из следующих:

  • Nec_24000
  • Nec_8000
  • Bys_24000
  • Bys_8000
  • May_24000
  • May_8000
  • Tur_24000
  • Tur_8000

Можно послушать примеры голосов в разделе Примеры голосов для синтеза

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

Описание 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, но в несколько раз меньшим по объему

Особенности запроса

  • Если заголовок Content-Type имеет значение application/text, в теле запроса передаётся текст в формате UTF8. Пример:
Привет из 1984!
  • Если заголовок Content-Type имеет значение application/ssml, в теле запроса передаётся текст в SSML-разметке в формате UTF8. Пример:
<speak>Аббревиатура <say-as interpret-as="characters">НДФЛ</say-as></speak>
  • Максимальный размер тела запроса независимо от значения заголовка Content-Type равен 4000 символам (включая пробелы и SSML-разметку).

Ответ

Тело 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-файл с нашей страницы на GitHub.

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

При обращении по 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 строка

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

Любое значение из следующих:

  • Nec_24000
  • Nec_8000
  • Bys_24000
  • Bys_8000
  • May_24000
  • May_8000
  • Tur_24000
  • Tur_8000

Можно послушать примеры голосов в разделе Примеры голосов для синтеза

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

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

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

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

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

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

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

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

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

Код Описание

3

INVALID_ARGUMENT

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

7

PERMISSION_DENIED

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

9

RESOURCE_EXHAUSTED

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

13

INTERNAL

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

16

UNAUTHENTICATED

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

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

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

Мы подготовили пример клиентского приложения на Python в GitHub. Следите за нашей страницей на GitHub, скоро там появятся примеры клиентского приложения на других популярных языках программирования.

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

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

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

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

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

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

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

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

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

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

Tur_8000

Как из текста получить синтез

  1. Отправьте HTTPS POST запрос на адрес https://smartspeech.sber.ru/rest/v1/text:synthesize. Запрос должен содержать следующую информацию:
  2. Информация для аутентификации в заголовке в виде JWE-токена
  3. Параметры синтеза (голос, формат и т.д.)
  4. В теле – текст для генерации либо в виде простого текста в формате UTF8, либо в виде SSML-разметки
  5. В случае успешной аутентификации выполнится синтез текста.
  6. Тело HTTP-ответа содержит бинарное представление синтезированного звука в запрошенном формате, если запрос обработан успешно (код ответа 200). Описание кодов ответа вы найдёте на в подразделе Формат ответа при неуспешном запросе.

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

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

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

Как улучшить синтез

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

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

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