Click here to read English Guide.

1. Вступление

Уважаемый клиент сервиса VoiceFabric! Если Вы читаете этот документ, значит, Вы уже успешно прошли регистрацию на сайте www.VoiceFabric.ru и находитесь в своем личном кабинете.

Данный документ описывает способ взаимодействия с сервисом VoiceFabric с целью получения возможности озвучивания любых текстовых сообщений, используя технологию синтеза речи. Все, что Вам нужно будет сделать – это послать желаемый текст в виде web-запроса на сервис VoiceFabric, а в ответ получить звуковой файл.

Необходимо также сказать, что описанный ниже способ взаимодействия с сервисом VoiceFabric, является не единственный способом озвучивания текстовых сообщений с помощью синтеза речи. Любые текстовые сообщения можно легко и быстро озвучивать, используя специальный web-интерфейс.

2. Принцип работы

Обмен информацией между API-сервисом VoiceFabric и приложением/устройством пользователя осуществляется по протоколу HTTPS.

Текст, который не превышает 4096 символов, может передаваться на синтез запросом GET. Текст объемом до 10 Мб может передаваться на синтез запросом POST.

Формат выходного звукового файла беззаголовочный (raw), codec=pcm, bit=16, rate=8000 или 22050 (зависит от голоса). Формат можно получить в ответе из заголовка Сontent-type.
Все запросы должны быть сформированы согласно HTTP-протоколу. Параметры строки запроса: UrlEncode, разделитель & и т.д.

3. Запрос

3.1 GET-метод получения аудио

При использовании метода GET текст для синтеза передается в строке запроса.
Пример запроса:

https://voicefabric.ru/WSServer/ws/tts?apikey=5d1f2d0a-3da1-48be-8597-aa6072f2e71a&id=myProgramId548218595186072f2e71a&ttsVoice=Владимир8000&textFormat=text/plain&text=ЦРТ

3.2 POST-метод получения аудио

При использовании метода POST текст для синтеза передается в теле запроса.

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

POST /WSServer/ws/tts HTTP/1.1
Host: voicefabric.ru
Connection: keep-alive
Content-Length: 712
Cache-Control: no-cache
Origin: custom_header
User-Agent: your_app_name
Content-Type: multipart/form-data; boundary=----WebKitFormBoundarySTYuoc5A3sdr6UGO
Accept: */*
Accept-Encoding: gzip,deflate,sdch
Cookie: doesNotMatter=true

------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="apikey"

5d1f2d0a-3da1-48be-8597-aa6072f2e71a
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="id"

myProgramId548218595186072f2e71a
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="ttsVoice"

Владимир8000
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="textFormat"

text/plain
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="text"

ЦРТ
------WebKitFormBoundaryPS1dTr66xqcrvKo5--

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

Параметр

Важность

Описание

apikey

Обязательный

API-ключ для авторизации на сервере. Содержит 32 символа: цифры и латинские буквы (0-9, a-z, A-Z).

id

Необязательный

Идентификатор пользовательского приложения или устройства. Генерируется непосредственно на сервере пользовательского приложения или устройства.
Должен состоять из 32-х символов и содержать цифры и латинские буквы (0-9, a-z, A-Z).

ttsVoice

Необязательный

Голос, который используется для синтеза текста. Если голос не задан, синтез выполняется голосом по умолчанию.
Список поддерживаемых голосов с частотой 8 кГц:

  • Владимир8000 – голос по умолчанию,
  • Юлия8000,
  • Анна8000,
  • Виктория8000,
  • Александр8000,
  • Мария8000,
  • Лидия8000,
  • Carol8000,
  • Asel8000.

Список поддерживаемых голосов с частотой 22050 Гц:

  • Владимир,
  • Юлия,
  • Анна,
  • Виктория,
  • Александр,
  • Мария,
  • Лидия,
  • Carol,
  • Asel.

textFormat

Необязательный

Формат текста для синтеза.
Если в запросе передается обычный текст без разметки, значение – text/plain. Значение по умолчанию.
Если в запросе передается текст с разметкой ssml, значение – application/synthesis+ssml.

text

Обязательный для GET и POST через html-формы. Для остальных POST - запросов текст передается в теле запроса.

Текст для синтеза. Текст должен передаваться в кодировке UTF-8.
Для GET-запроса текст должен содержать не более 4096 символов.
Для POST-запроса размер текста не должен превышать 10 Мб.

 

4. Ответ

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

При успешном синтезе (код 200) в ответе могут присылаться следующие заголовки:

Заголовок

Описание

Transfer-Encoding

Признак режима «chunked».

Content-Length

Размер возвращаемых аудиоданных.

Content-Disposition

Предлагаемое имя файла с расширением.

tts-requestid

Идентификатор запроса.

tts-engineSID

Внутренний идентификатор сессии.

tts-billingSID

Идентификатор сессии биллинга.

 

4.2 Примеры ответа

При длительном синтезе аудио API-сервис может отдавать данные в режиме «chunked». При этом ответ содержит соответствующий заголовок Transfer-Encoding: chunked.

Если система синтезировала текст и готова отправить его в ответном сообщении меньше чем за одну секунду - то это быстрый синтез, если больше - то это длительный синтез (chunked mode).

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Connection: keep-alive
tts-requestid: b84343b8-5605-4fc8-a83e-3756fd97b57b
Content-Disposition: attachment; filename="b84343b8-5605-4fc8-a83e-3756fd97b57b.raw"
tts-engineSID: FFFFFEC100312732_10C2_344
tts-billingSID: 7e2c59d1-86cd-404f-afa3-a4437bd04ca8

RAW_BINARY_DATA_PAYLOAD

Если данные передаются за один раз, ответ содержит заголовок Content-Length.
Пример ответа:

HTTP/1.1 200 OK
Content-Length: 26512
Connection: keep-alive
tts-requestid: b84343b8-5605-4fc8-a83e-3756fd97b57b
Content-Disposition: attachment; filename="b84343b8-5605-4fc8-a83e-3756fd97b57b.raw"
tts-engineSID: FFFFFEC100312732_10C2_344
tts-billingSID: 7e2c59d1-86cd-404f-afa3-a4437bd04ca8

BINARY_DATA_PAYLOAD

4.3 Коды ответа

Значение

Описание

200

Запрос корректный, хотя бы часть аудиофайла сформирована.

400

Запрос сформирован некорректно. Возможно, отсутствует обязательный параметр.

401

Неправильный API-ключ.

403

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

413

В POST-запросе превышен допустимый размер текста – 10 Мб.

414

В GET-запросе превышено допустимое количество символов в тексте – 4096.

415

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

419

Превышен таймаут ожидания в очереди.

500

Не удается конкретизировать возникшую ошибку сервера.

 

В случае клиентских ошибок (коды 4хх) ответ может содержать более детальную информацию. Обратите внимание на текстовое описание.

 

1. Introduction

This guide is intended for users who signed up for a website www.VoiceFabric.ru.

This guide describes a method of interaction with VoiceFabric service for enabling user to play any text message by pronouncing it with speech synthesis technology. All you need is to send necessary text as a request to VoiceFabric service. As a result, you will receive an audio file.

The described method of interaction with VoiceFabric service is not the only one method of playing text messages using speech synthesis. Any text message can be easily played using special web interface.

2. Operating structure

Communication of VoiceFabric API service with you application/device is performed through HTTPS protocol.

Text that contains less than 4096 symbols can be synthesized by GET request. Any text of up to 10 Mb can be synthesized by POST request.

Output audio file has a headerless (raw), codec = pcm, bit = 16, rate = 8000 or 22050 (depending on voice) format.
You can use sox utility for saving raw data in wav-container. Example :

sox -r 22050 -e signed -b 16 audio.raw audio.wav
, where 22050 - sampling rate (rate), а 16 - bit of quantization (bit).
All requests must be formed according to HTTP protocol. String parameters are the following: UrlEncode, & separator and etc.

3. Request

3.1 GET method of getting audio file

Using GET method, text is sent in a request string.
Example:

https://voicefabric.ru/WSServer/ws/tts?apikey=5d1f2d0a-3da1-48be-8597-aa6072f2e71a&id=myProgramId548218595186072f2e71a&ttsVoice=Владимир8000&textFormat=text/plain&text=ЦРТ

3.2 POST method of getting audio file

Using POST method, text is sent in a body part of a request.

Example of request dump:

POST /WSServer/ws/tts HTTP/1.1
Host: voicefabric.ru
Connection: keep-alive
Content-Length: 712
Cache-Control: no-cache
Origin: custom_header
User-Agent: your_app_name
Content-Type: multipart/form-data; boundary=----WebKitFormBoundarySTYuoc5A3sdr6UGO
Accept: */*
Accept-Encoding: gzip,deflate,sdch
Cookie: doesNotMatter=true

------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="apikey"

5d1f2d0a-3da1-48be-8597-aa6072f2e71a
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="id"

myProgramId548218595186072f2e71a
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="ttsVoice"

Владимир8000
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="textFormat"

text/plain
------WebKitFormBoundaryPS1dTr66xqcrvKo5
Content-Disposition: form-data; name="text"

ЦРТ
------WebKitFormBoundaryPS1dTr66xqcrvKo5--

3.3 Request settings

Settings

Importance

Description

apikey

Mandatory

API key for the authorization at the server. It contains 32 symbols: numbers and Latin letters (0-9, a-z, A-Z).

id

Optional

ID of user application or device. It is generated on the server of user application or device.
It must contain 32 symbols: numbers and Latin letters (0-9, a-z, A-Z).

ttsVoice

Optional

Voice which is used for synthesis. If voice is not specified, it is set by default.
List of supported voices with 8 kHz frequency rate:

  • Владимир8000 - is set by default,
  • Юлия8000,
  • Анна8000,
  • Виктория8000,
  • Александр8000,
  • Мария8000,
  • Лидия8000,
  • Carol8000,
  • Asel8000.

List of supported voices with 22050 Hz frequency rate:

  • Владимир,
  • Юлия,
  • Анна,
  • Виктория,
  • Александр,
  • Мария,
  • Лидия,
  • Carol,
  • Asel.

textFormat

Optional

Text form for synthesis.
If request sends a text without a layout, it has a text/plain value. This value is set by default.
If request sends a text with ssml layout, it has an application/synthesis+ssml value.

text

Mandatory for GET and POST through html forms. For other POST requests, text is sent in a body part of the request.

Text for synthesis. Text must be coded in UTF-8.
For GET request, text must contain less than 4096 symbols.
For POST request, the text size should not exceed 10 Mb.

 

4. Response

4.1 Response headers

If text is synthesized successfully (code 200), the following headers can be sent in response:

Header

Header

Transfer-Encoding

Chunked mode.

Content-Length

Size of response audio data.

Content-Disposition

Suggested file name with extension.

tts-requestid

Request ID.

tts-engineSID

Internal session ID.

tts-billingSID

Billing session ID.

 

4.2 Response examples

In case of a continuous audio synthesis, API service can send data in a chunked mode. The response has the corresponding header Transfer-Encoding: chunked.

If system synthesizes text and can send it back in less than one second, it is a quick synthesis. If it takes more time, it is a longtime synthesis (chunked mode).

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Connection: keep-alive
tts-requestid: b84343b8-5605-4fc8-a83e-3756fd97b57b
Content-Disposition: attachment; filename="b84343b8-5605-4fc8-a83e-3756fd97b57b.raw"
tts-engineSID: FFFFFEC100312732_10C2_344
tts-billingSID: 7e2c59d1-86cd-404f-afa3-a4437bd04ca8

RAW_BINARY_DATA_PAYLOAD

If data is sent at once, the response has a header Content-Length.
For example:

HTTP/1.1 200 OK
Content-Length: 26512
Connection: keep-alive
tts-requestid: b84343b8-5605-4fc8-a83e-3756fd97b57b
Content-Disposition: attachment; filename="b84343b8-5605-4fc8-a83e-3756fd97b57b.raw"
tts-engineSID: FFFFFEC100312732_10C2_344
tts-billingSID: 7e2c59d1-86cd-404f-afa3-a4437bd04ca8

BINARY_DATA_PAYLOAD

4.3 Response codes

Code

Description

200

Correct request; even the part of audio file is formed.

400

Request is not correctly formed. Mandatory setting may not be specified.

401

Invalid API key.

403

The service is unavailable because of restrictions. Possibly due to insufficient balance.

413

POST request exceeded the allowable text size – 10 Mb.

414

GET request exceeded the allowable number of symbols – 4096.

415

The request specified unsupported format for one of the settings.

419

Waiting for request timeout period has expired.

500

Cannot specify appeared server error.

 

If client errors (code 4xx) appear, the response may provide more detailed information. Read text description carefully.