Описание метода API

Генерирует речь по переданному тексту.

HTTP-запрос

POST https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize

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

Для всех параметров обязательно используйте URL-кодирование. Максимальный размер тела POST-запроса 30 КБ.

Параметр Описание
text Обязательный параметр.
Текст, который нужно озвучить, в кодировке UTF-8.
Для передачи слов-омографов используйте + перед ударной гласной. Например, гот+ов или def+ect.
Чтобы отметить паузу между словами, используйте -.
Ограничение на длину строки: 5000 символов.
lang Язык.
Допустимые значения:
  • ru-RU (по умолчанию) — русский язык,
  • en-US — английский язык;
  • tr-TR — турецкий язык.
voice Голос синтезированной речи.
Можно выбрать один из следующих голосов:
  • женские голоса: alyss, jane, oksana и omazh;
  • мужские голоса: zahar и ermil.
Значение параметра по умолчанию: oksana.
emotion Эмоциональная окраска голоса.
Допустимые значения:
  • good — радостный, доброжелательный;
  • evil — раздраженный;
  • neutral (по умолчанию) — нейтральный.
speed Скорость (темп) синтезированной речи.
Скорость речи задается дробным числом в диапазоне от 0.1 до 3.0. Где:
  • 3.0 — самый быстрый темп;
  • 1.0 (по умолчанию) — средняя скорость человеческой речи;
  • 0.1 — самый медленный темп.
format Формат синтезируемого аудио.
Допустимые значения:
  • lpcm — аудиофайл синтезируется в формате LPCM без WAV-заголовка. Характеристики аудио:
    • Дискретизация — 8, 16 или 48 kHz в зависимости от значения параметра sampleRateHertz.
    • Разрядность квантования — 16-bit.
    • Порядок байтов — обратный (little-endian).
    • Аудиоданные хранятся как знаковые числа (signed integer).
  • oggopus (по умолчанию) — данные в аудиофайле кодируются с помощью аудиокодека OPUS и упаковываются в контейнер OGG (OggOpus).
sampleRateHertz Частота дискретизации синтезируемого аудио.
Применяется, если значение format равно lpcm. Допустимые значения:
  • 48000 (по умолчанию) — частота дискретизации 48 кГц;
  • 16000 — частота дискретизации 16 кГц;
  • 8000 — частота дискретизации 8 кГц.
folderId Обязательный параметр.
Идентификатор вашего каталога.
Подробнее о том, как узнать идентификатор каталога читайте в разделе Авторизация в API.

Ответ

Если синтез прошел успешно, в ответе будет бинарное содержимое аудиофайла. Формат выходных данных зависит от значения параметра format.

Примеры

Превратить текст в речь в формате Ogg

В этом примере текст "Hello World" синтезируется и записывается в аудиофайл.

По умолчанию данные в аудиофайле кодируются с помощью аудиокодека OPUS и упаковываются в контейнер OGG (OggOpus).

$ export FOLDER_ID=b1gvmob95yysaplct532
$ export IAM_TOKEN=CggaATEVAgA...
$ curl -X POST \
     -H "Authorization: Bearer ${IAM_TOKEN}" \
     --data-urlencode "text=Hello World" \
     -d "lang=en-US&folderId=${FOLDER_ID}" \
     "https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize" > speech.ogg
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
using System.IO;

namespace TTS
{
  class Program
  {
    static void Main()
    {
      Tts().GetAwaiter().GetResult();
    }

    static async Task Tts()
    {
      const string iamToken = "CggaATEVAgA..."; // Укажите IAM-токен.
      const string folderId = "b1gvmob95yysaplct532"; // Укажите ID каталога.

      HttpClient client = new HttpClient();
      client.DefaultRequestHeaders.Add("Authorization", "Bearer " + iamToken);
      var values = new Dictionary<string, string>
      {
        { "text", "Hello World" },
        { "lang", "en-US" },
        { "folderId", folderId }
      };
      var content = new FormUrlEncodedContent(values);
      var response = await client.PostAsync("https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize", content);
      var responseBytes = await response.Content.ReadAsByteArrayAsync();
      File.WriteAllBytes("speech.ogg", responseBytes);
    }
  }
}
  1. Создайте файл, например test.py, и добавьте в него следующий код:

    import argparse
    import requests
    
    
    def synthesize(folder_id, iam_token, text):
        url = 'https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize'
        headers = {
            'Authorization': 'Bearer ' + iam_token,
        }
    
        data = {
            'text': text,
            'lang': 'en-US',
            'folderId': folder_id
        }
    
        with requests.post(url, headers=headers, data=data, stream=True) as resp:
            if resp.status_code != 200:
                raise RuntimeError("Invalid response received: code: %d, message: %s" % (resp.status_code, resp.text))
    
            for chunk in resp.iter_content(chunk_size=None):
                yield chunk
    
    
    if __name__ == "__main__":
        parser = argparse.ArgumentParser()
        parser.add_argument("--token", required=True, help="IAM token")
        parser.add_argument("--folder_id", required=True, help="Folder id")
        parser.add_argument("--text", required=True, help="Text for synthesize")
        parser.add_argument("--output", required=True, help="Output file name")
        args = parser.parse_args()
    
        with open(args.output, "wb") as f:
            for audio_content in synthesize(args.folder_id, args.token, args.text):
                f.write(audio_content)
    
  2. Выполните созданный файл, передав в аргументах IAM-токен, идентификатор каталога, текст и имя файла для записи аудио:

    $ export FOLDER_ID=b1gvmob95yysaplct532
    $ export IAM_TOKEN=CggaATEVAgA...
    $ python test.py --token ${IAM_TOKEN} --folder_id ${FOLDER_ID} --output speech.ogg --text "Hello World"
    
<?

$token = 'CggaATEVAgA...'; # IAM-токен
$folderId = "b1gvmob95yysaplct532"; # Идентификатор каталога
$url = "https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize";

$post = "text=" . urlencode("Hello World") . "&lang=en-US&folderId=${folderId}";
$headers = ['Authorization: Bearer ' . $token];
$ch = curl_init();

curl_setopt($ch, CURLOPT_AUTOREFERER, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
if ($post !== false) {
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);


$response = curl_exec($ch);
if (curl_errno($ch)) {
    print "Error: " . curl_error($ch);
}
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) != 200) {
    $decodedResponse = json_decode($response, true);
    echo "Error code: " . $decodedResponse["error_code"] . "\r\n";
    echo "Error message: " . $decodedResponse["error_message"] . "\r\n";
} else {
    file_put_contents("speech.ogg", $response);
}
curl_close($ch);

Превратить текст в речь в формате WAV

В этом примере переданный текст синтезируется в формате LPCM с частотой дискретизации 48kHz и сохраняется в файле speech.raw. Затем этот файл конвертируется в формат WAV с помощью утилиты SoX.

  1. Синтезируйте файл в формате LCPM:

    $ export FOLDER_ID=b1gvmob95yysaplct532
    $ export IAM_TOKEN=CggaATEVAgA...
    $ curl -X POST \
        -H "Authorization: Bearer ${IAM_TOKEN}" \
        -o speech.raw \
        --data-urlencode "text=Hello World" \
        -d "lang=en-US&folderId=${FOLDER_ID}&format=lpcm&sampleRateHertz=48000" \
        https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize
    
    using System;
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Threading.Tasks;
    using System.IO;
    
    namespace TTS
    {
      class Program
      {
        static void Main()
        {
          Tts().GetAwaiter().GetResult();
        }
    
        static async Task Tts()
        {
          const string iamToken = "CggaATEVAgA..."; // Укажите IAM-токен.
          const string folderId = "b1gvmob95yysaplct532"; // Укажите ID каталога.
    
          HttpClient client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", "Bearer " + iamToken);
          var values = new Dictionary<string, string>
          {
            { "text", "Hello World" },
            { "lang", "en-US" },
            { "folderId", folderId },
            { 'format': 'lpcm' },
            { 'sampleRateHertz': 48000 }
          };
          var content = new FormUrlEncodedContent(values);
          var response = await client.PostAsync("https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize", content);
          var responseBytes = await response.Content.ReadAsByteArrayAsync();
          File.WriteAllBytes("speech.raw", responseBytes);
        }
      }
    }
    
    1. Создайте файл, например test.py, и добавьте в него следующий код:

      import argparse
      import requests
      
      
      def synthesize(folder_id, iam_token, text):
          url = 'https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize'
          headers = {
              'Authorization': 'Bearer ' + iam_token,
          }
      
          data = {
              'text': text,
              'lang': 'en-US',
              'folderId': folder_id,
              'format': 'lpcm',
              'sampleRateHertz': 48000,
          }
      
          with requests.post(url, headers=headers, data=data, stream=True) as resp:
              if resp.status_code != 200:
                  raise RuntimeError("Invalid response received: code: %d, message: %s" % (resp.status_code, resp.text))
      
              for chunk in resp.iter_content(chunk_size=None):
                  yield chunk
      
      
      if __name__ == "__main__":
          parser = argparse.ArgumentParser()
          parser.add_argument("--token", required=True, help="IAM token")
          parser.add_argument("--folder_id", required=True, help="Folder id")
          parser.add_argument("--text", required=True, help="Text for synthesize")
          parser.add_argument("--output", required=True, help="Output file name")
          args = parser.parse_args()
      
          with open(args.output, "wb") as f:
              for audio_content in synthesize(args.folder_id, args.token, args.text):
                  f.write(audio_content)
      
    2. Выполните созданный файл, передав в аргументах IAM-токен, идентификатор каталога, текст и имя файла для записи аудио:

      $ export FOLDER_ID=b1gvmob95yysaplct532
      $ export IAM_TOKEN=CggaATEVAgA...
      $ python test.py --token ${IAM_TOKEN} --folder_id ${FOLDER_ID} --output speech.raw --text "Hello World"
      
    <?
    
    const FORMAT_PCM = "lpcm";
    const FORMAT_OPUS = "oggopus";
    
    $token = 'CggaATEVAgA...'; # IAM-токен
    $folderId = "b1gvmob95yysaplct532"; # Идентификатор каталога
    $url = "https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize";
    $post = "text=" . urlencode("Hello World") . "&lang=en-US&folderId=${folderId}&sampleRateHertz=48000&format=" . FORMAT_PCM;
    $headers = ['Authorization: Bearer ' . $token];
    $ch = curl_init();
    
    curl_setopt($ch, CURLOPT_AUTOREFERER, TRUE);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    if ($post !== false) {
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    
    $response = curl_exec($ch);
    if (curl_errno($ch)) {
        print "Error: " . curl_error($ch);
    }
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) != 200) {
        $decodedResponse = json_decode($response, true);
        echo "Error code: " . $decodedResponse["error_code"] . "\r\n";
        echo "Error message: " . $decodedResponse["error_message"] . "\r\n";
    } else {
        file_put_contents("speech.raw", $response);
    }
    curl_close($ch);
    
  2. Cконвертируйте полученный файл в формат WAV с помощью утилиты SoX.

    $ sox -r 48000 -b 16 -e signed-integer -c 1 speech.raw speech.wav