Yandex Cloud
Поиск
Связаться с намиПодключиться
  • Истории успеха
  • Документация
  • Блог
  • Все сервисы
  • Статус работы сервисов
    • Популярные
    • Инфраструктура и сеть
    • Платформа данных
    • Контейнеры
    • Инструменты разработчика
    • Бессерверные вычисления
    • Безопасность
    • Мониторинг и управление ресурсами
    • AI Studio
    • Бизнес-инструменты
  • Все решения
    • По отраслям
    • По типу задач
    • Экономика платформы
    • Безопасность
    • Техническая поддержка
    • Каталог партнёров
    • Обучение и сертификация
    • Облако для стартапов
    • Облако для крупного бизнеса
    • Центр технологий для общества
    • Облако для интеграторов
    • Поддержка IT-бизнеса
    • Облако для фрилансеров
    • Обучение и сертификация
    • Блог
    • Документация
    • Контент-программа
    • Мероприятия и вебинары
    • Контакты, чаты и сообщества
    • Идеи
    • Тарифы Yandex Cloud
    • Промоакции и free tier
    • Правила тарификации
  • Истории успеха
  • Документация
  • Блог
Проект Яндекса
© 2025 ООО «Яндекс.Облако»
Страница сервиса
Yandex SpeechKit
Документация
Yandex SpeechKit
  • Обзор технологий SpeechKit
    • Обзор
    • Аутентификация в API
      • API v1
        • Overview
          • Overview
          • UtteranceSynthesis
  • Поддерживаемые форматы аудио
  • Интеграция телефонии
  • Квоты и лимиты
  • Управление доступом
  • Правила тарификации
  • Аудитные логи Audit Trails

В этой статье:

  • HTTP request
  • Body parameters
  • TextTemplate
  • TextVariable
  • Hints
  • AudioTemplate
  • AudioContent
  • AudioFormatOptions
  • RawAudio
  • ContainerAudio
  • AudioVariable
  • DurationHint
  • Response
  • AudioChunk
  • TextChunk
  1. Справочники API
  2. Синтез
  3. API v3 REST (англ.)
  4. Synthesizer
  5. UtteranceSynthesis

SpeechKit Synthesis Service API v3, REST: Synthesizer.UtteranceSynthesis

Статья создана
Yandex Cloud
Обновлена 8 августа 2025 г.
  • HTTP request
  • Body parameters
  • TextTemplate
  • TextVariable
  • Hints
  • AudioTemplate
  • AudioContent
  • AudioFormatOptions
  • RawAudio
  • ContainerAudio
  • AudioVariable
  • DurationHint
  • Response
  • AudioChunk
  • TextChunk

Synthesizing text into speech.

HTTP requestHTTP request

POST https://tts.api.cloud.yandex.net/tts/v3/utteranceSynthesis

Body parametersBody parameters

{
  "model": "string",
  // Includes only one of the fields `text`, `textTemplate`
  "text": "string",
  "textTemplate": {
    "textTemplate": "string",
    "variables": [
      {
        "variableName": "string",
        "variableValue": "string"
      }
    ]
  },
  // end of the list of possible fields
  "hints": [
    {
      // Includes only one of the fields `voice`, `audioTemplate`, `speed`, `volume`, `role`, `pitchShift`, `duration`
      "voice": "string",
      "audioTemplate": {
        "audio": {
          // Includes only one of the fields `content`
          "content": "string",
          // end of the list of possible fields
          "audioSpec": {
            // Includes only one of the fields `rawAudio`, `containerAudio`
            "rawAudio": {
              "audioEncoding": "string",
              "sampleRateHertz": "string"
            },
            "containerAudio": {
              "containerAudioType": "string"
            }
            // end of the list of possible fields
          }
        },
        "textTemplate": {
          "textTemplate": "string",
          "variables": [
            {
              "variableName": "string",
              "variableValue": "string"
            }
          ]
        },
        "variables": [
          {
            "variableName": "string",
            "variableStartMs": "string",
            "variableLengthMs": "string"
          }
        ]
      },
      "speed": "string",
      "volume": "string",
      "role": "string",
      "pitchShift": "string",
      "duration": {
        "policy": "string",
        "durationMs": "string"
      }
      // end of the list of possible fields
    }
  ],
  "outputAudioSpec": {
    // Includes only one of the fields `rawAudio`, `containerAudio`
    "rawAudio": {
      "audioEncoding": "string",
      "sampleRateHertz": "string"
    },
    "containerAudio": {
      "containerAudioType": "string"
    }
    // end of the list of possible fields
  },
  "loudnessNormalizationType": "string",
  "unsafeMode": "boolean"
}

Field

Description

model

string

The name of the model.
Specifies basic synthesis functionality. Currently should be empty. Do not use it.

text

string

Raw text (e.g. "Hello, Alice").

Includes only one of the fields text, textTemplate.

Text to synthesis, one of text synthesis markups.

textTemplate

TextTemplate

Text template instance, e.g. {"Hello, {username}" with username="Alice"}.

Includes only one of the fields text, textTemplate.

Text to synthesis, one of text synthesis markups.

hints[]

Hints

Optional hints for synthesis.

outputAudioSpec

AudioFormatOptions

Optional. Default: 22050 Hz, linear 16-bit signed little-endian PCM, with WAV header

loudnessNormalizationType

enum (LoudnessNormalizationType)

Specifies type of loudness normalization.
Optional. Default: LUFS.

  • LOUDNESS_NORMALIZATION_TYPE_UNSPECIFIED
  • MAX_PEAK: The type of normalization, wherein the gain is changed to bring the highest PCM sample value or analog signal peak to a given level.
  • LUFS: The type of normalization based on EBU R 128 recommendation.

unsafeMode

boolean

Optional. Automatically split long text to several utterances and bill accordingly. Some degradation in service quality is possible.

TextTemplateTextTemplate

Field

Description

textTemplate

string

Template text.

Sample:The {animal} goes to the {place}.

variables[]

TextVariable

Defining variables in template text.

Sample: {animal: cat, place: forest}

TextVariableTextVariable

Field

Description

variableName

string

The name of the variable.

variableValue

string

The text of the variable.

HintsHints

Field

Description

voice

string

Name of speaker to use.

Includes only one of the fields voice, audioTemplate, speed, volume, role, pitchShift, duration.

The hint for TTS engine to specify synthesised audio characteristics.

audioTemplate

AudioTemplate

Template for synthesizing.

Includes only one of the fields voice, audioTemplate, speed, volume, role, pitchShift, duration.

The hint for TTS engine to specify synthesised audio characteristics.

speed

string

Hint to change speed.

Includes only one of the fields voice, audioTemplate, speed, volume, role, pitchShift, duration.

The hint for TTS engine to specify synthesised audio characteristics.

volume

string

Hint to regulate normalization level.

  • For MAX_PEAK loudness_normalization_type: volume changes in a range (0;1], default value is 0.7.
  • For LUFS loudness_normalization_type: volume changes in a range [-145;0), default value is -19.

Includes only one of the fields voice, audioTemplate, speed, volume, role, pitchShift, duration.

The hint for TTS engine to specify synthesised audio characteristics.

role

string

Hint to specify pronunciation character for the speaker.

Includes only one of the fields voice, audioTemplate, speed, volume, role, pitchShift, duration.

The hint for TTS engine to specify synthesised audio characteristics.

pitchShift

string

Hint to increase (or decrease) speaker's pitch, measured in Hz. Valid values are in range [-1000;1000], default value is 0.

Includes only one of the fields voice, audioTemplate, speed, volume, role, pitchShift, duration.

The hint for TTS engine to specify synthesised audio characteristics.

duration

DurationHint

Hint to limit both minimum and maximum audio duration.

Includes only one of the fields voice, audioTemplate, speed, volume, role, pitchShift, duration.

The hint for TTS engine to specify synthesised audio characteristics.

AudioTemplateAudioTemplate

Field

Description

audio

AudioContent

Audio file.

textTemplate

TextTemplate

Template and description of its variables.

variables[]

AudioVariable

Describing variables in audio.

AudioContentAudioContent

Field

Description

content

string (bytes)

Bytes with audio data.

Includes only one of the fields content.

The audio source to read the data from.

audioSpec

AudioFormatOptions

Description of the audio format.

AudioFormatOptionsAudioFormatOptions

Field

Description

rawAudio

RawAudio

The audio format specified in request parameters.

Includes only one of the fields rawAudio, containerAudio.

containerAudio

ContainerAudio

The audio format specified inside the container metadata.

Includes only one of the fields rawAudio, containerAudio.

RawAudioRawAudio

Field

Description

audioEncoding

enum (AudioEncoding)

Encoding type.

  • AUDIO_ENCODING_UNSPECIFIED
  • LINEAR16_PCM: Audio bit depth 16-bit signed little-endian (Linear PCM).

sampleRateHertz

string (int64)

Sampling frequency of the signal.

ContainerAudioContainerAudio

Field

Description

containerAudioType

enum (ContainerAudioType)

  • CONTAINER_AUDIO_TYPE_UNSPECIFIED
  • WAV: Audio bit depth 16-bit signed little-endian (Linear PCM).
  • OGG_OPUS: Data is encoded using the OPUS audio codec and compressed using the OGG container format.
  • MP3: Data is encoded using MPEG-1/2 Layer III and compressed using the MP3 container format.

AudioVariableAudioVariable

Field

Description

variableName

string

The name of the variable.

variableStartMs

string (int64)

Start time of the variable in milliseconds.

variableLengthMs

string (int64)

Length of the variable in milliseconds.

DurationHintDurationHint

Field

Description

policy

enum (DurationHintPolicy)

Type of duration constraint.

  • DURATION_HINT_POLICY_UNSPECIFIED
  • EXACT_DURATION: Limit audio duration to exact value.
  • MIN_DURATION: Limit the minimum audio duration.
  • MAX_DURATION: Limit the maximum audio duration.

durationMs

string (int64)

Constraint on audio duration in milliseconds.

ResponseResponse

HTTP Code: 200 - OK

{
  "audioChunk": {
    "data": "string"
  },
  "textChunk": {
    "text": "string"
  },
  "startMs": "string",
  "lengthMs": "string"
}

Field

Description

audioChunk

AudioChunk

Part of synthesized audio.

textChunk

TextChunk

Part of synthesized text.

startMs

string (int64)

Start time of the audio chunk in milliseconds.

lengthMs

string (int64)

Length of the audio chunk in milliseconds.

AudioChunkAudioChunk

Field

Description

data

string (bytes)

Sequence of bytes of the synthesized audio in format specified in output_audio_spec.

TextChunkTextChunk

Field

Description

text

string

Synthesized text.

Была ли статья полезна?

Предыдущая
Overview
Следующая
О Python SDK
Проект Яндекса
© 2025 ООО «Яндекс.Облако»