Преобразование текста в речь (TTS)
Преобразуйте текст в естественную речь.
Преобразуйте текст в речь с помощью синтеза голоса на базе ИИ. Результатом является аудиофайл в формате MP3.
Аутентификация
Укажите свой API-ключ в заголовке Authorization.
Тело запроса
| Параметр | Обязательно | Тип | Описание |
|---|---|---|---|
| text | обязательный | строка | Текст для преобразования (макс. 1500 символов) |
| output_format | по выбору | строка | Желаемый формат аудио на выходе. Указывается в виде codec_sampleRate_bitrate (например, mp3_22050_32). Значение по умолчанию — mp3_44100_128. Полный список приведен ниже в разделе «Выходные форматы». |
| voice_id | обязательный | целое число | Голосовая идентификация от список голосов. |
| prerecording | по выбору | целое число | 1 (базовая обработка), 2 (обработка с помощью ИИ / арабская огласовка) или 3 (ИИ-поэт). Варианты 2 и 3 доступны только для контента на арабском языке; см. раздел «Язык». |
| language | по выбору | строка | Язык контента в формате кода ISO 639-1, например ar или en (допускаются коды регионов, такие как ar-JO). Этот параметр определяет, какие режимы предварительной записи разрешены, и не передается голосовому движку. Режимы 2 и 3 доступны только для арабского языка (ar). Если язык не указан, режимы 2 и 3 подразумевают использование арабского языка, поэтому существующие интеграции продолжают работать. При использовании любого другого языка с режимами 2 или 3, а также при указании неизвестного кода, возвращается ошибка 400 INVALID_REQUEST с указанием причины в поле details.language. |
| voice_settings | по выбору | строка (JSON) | Параметры настройки голоса |
Поддерживаемые выходные форматы
Параметр output_format может принимать любое из следующих значений:
- MP3: mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
- PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000
- Опус: opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
- WAV: wav_16000, wav_22050, wav_24000, wav_44100, wav_48000 — 16-битный моно WAV — собственный вывод движка (без потерь). Недоступно в потоковом WebSocket — используйте там pcm_*.
Этот раздел носит справочный характер и позволяет пользователям выбрать подходящий формат, не перегружая основную таблицу запросов.
Двигатели и режимы
Каждый голос относится к одному из двух движков. В списке голосов он обозначается как voice_engine, и выбор голоса определяет, какие настройки будут применяться.
Каждый API-ключ предназначен для одного движка: стандартного (по умолчанию) или расширенного, выбранного при создании ключа. Ключ показывает и использует только голоса своего движка; чтобы работать с другим, создайте второй ключ.
- Стандартный движок (
standard) — студийные голоса с тремя режимами, варьирующими соотношение скорости, выразительности и цены. - Расширенный движок (
advanced, альфа) — собственные голоса, выраженные простым языком с учетом контекста, обстановки, стиля и темпа. Режимы здесь не применяются.
Стандартные режимы работы двигателя
| режим | Имя | Кредиты | Лучше всего подходит для |
|---|---|---|---|
emotion по умолчанию |
Эмоции и диалект | ×1 | Быстрая, выразительная речь с передачей эмоций и диалектов. Поддерживает теги эмоций, такие как [смех] и [шёпот]. |
quality |
Эмоции и диалект (высокое качество) | ×2 | Более богатые и естественные эмоции и диалекты. Требует немного больше времени. Поддерживает теги эмоций. |
studio |
Студийное качество | ×2 | Чистое, ровное студийное озвучивание с полным набором настроек голоса. Без тегов эмоций. |
Запросы без указания режима выполняются в режиме эмоций.
Объект настроек голоса
Стандартные звуки двигателя
| Параметр | Тип | Диапазон | По умолчанию | Описание |
|---|---|---|---|---|
| mode | строка | emotion, quality, studio | emotion | Стандартный режим движка. Качество и стоимость студии — ×2 кредита. См. раздел «Движки и режимы» выше. |
| temperature | целое число | 0 – 100 | 25 | Регулирует вариативность и выразительность речи. Низкие значения делают речь более стабильной и предсказуемой, тогда как высокие — усиливают разнообразие, спонтанность и креативность формулировок. |
| voice_similarity | целое число | 0 – 100 | 100 | Определяет, насколько точно сгенерированная речь соответствует выбранному голосовому профилю. Более высокие значения сохраняют характерные особенности исходного голоса, тогда как более низкие допускают больше отклонений в тоне и артикуляции. |
| speed | плавать | 0.7 – 1.2 | 1.0 | Регулирует темп речи. Значения ниже 1,0 замедляют речь для большей разборчивости, а значения выше 1,0 — увеличивают скорость речи. Только студийный режим; параметры эмоций и качества игнорируются. |
| enable_emotions устаревший | булев | false / true | — | По-прежнему принимается для обеспечения совместимости, но больше не влияет на результат. Вместо этого используйте mode. |
| fast_mode устаревший | целое число | 0, 1, or 2 | — | Параметр по-прежнему принимается для обеспечения совместимости, но больше не влияет на результат, так как режим emotion (эмоций) и так является быстрым вариантом. Для обработки аудио в реальном времени используйте потоковую конечную точку (streaming endpoint). |
В режимах «эмоция» (emotion) и «качество» (quality) за управление голосом отвечают параметры temperature и voice_similarity (любое значение в пределах диапазона используется без изменений), а параметр speed применяется только в режиме «студия» (studio).
Улучшенное звучание двигателя
| Параметр | Тип | Ценности | Описание |
|---|---|---|---|
| context | строка | до 500 символов | Самый сильный инструмент управления. Опишите акцент, эмоциональную окраску, настроение или цель — например: «Теплая документальная озвучка с левантийским акцентом». |
| setting | строка | до 500 символов | Обстановка и настроение, например: «Спокойная, камерная студия поздней ночью». |
| style | строка | neutral, warm, energetic, serious, cheerful, poetic | Общий стиль подачи. |
| pace | строка | slow, normal, fast | Темп речи. |
Голоса продвинутого движка игнорируют настройки режима и ползунки стандартного движка, возвращая результат в запрошенном формате (output_format). Генерация может занимать немного больше времени, чем при использовании стандартного движка.
Правила и ограничения для настроек голоса
- Неизвестные ключи, недопустимые значения режима, стиля или темпа, а также контекст или настройки длиной более 500 символов отклоняются с ошибкой 400 INVALID_REQUEST.
-
Для обеспечения совместимости, если для устаревшего параметра enable_emotions установлено значение true, следующие поля не должны включаться в voice_settings:
speed,fast_mode.
Цены
Кредиты = символы × (тариф предзаписи + плата за голос %) × множитель режима. Множитель: ×2 для quality и studio, ×1 для emotion и ×1,5 для каждого голоса движка Advanced.
Пример
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}' \
--output speech.mp3
# Advanced engine voice (voice_engine = "advanced")
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "مرحبا بك في منصة مكنة",
"voice_id": 2,
"voice_settings": {
"context": "A warm documentary read in a Levantine dialect.",
"pace": "slow"
}
}' \
--output speech-advanced.mp3
import requests
response = requests.post(
"https://moknah.io/api/v1/tts/generate/",
headers={
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
json={
"text": "مرحبا بك في منصة مكنة",
"voice_id": 1,
"prerecording": 1,
"language": "ar",
"voice_settings": {
"mode": "emotion",
"speed": 1.0,
"temperature": 25
}
}
)
with open("speech.mp3", "wb") as f:
f.write(response.content)
const response = await fetch(
'https://moknah.io/api/v1/tts/generate/',
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'مرحبا بك في منصة مكنة',
voice_id: 1,
prerecording: 1,
language: 'ar',
voice_settings: {
mode: 'emotion',
speed: 1.0,
temperature: 25
}
})
}
);
const blob = await response.blob();
// Save or play the audio
Ответ
Возвращает бинарные аудиоданные в запрошенном формате (по умолчанию — MP3) со следующими заголовками:
| Заголовок | Описание |
|---|---|
Content-Type |
Соответствует output_format: audio/mpeg для mp3_*, audio/ogg для opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 для pcm_* (сырые данные, 16 бит, little-endian, без заголовка). |
Ошибки
| Статус | Код | Описание |
|---|---|---|
400 |
INVALID_REQUEST | Недопустимые параметры (включая неизвестный режим, стиль или темп) |
401 |
UNAUTHORIZED | Неверный API-ключ |
402 |
INSUFFICIENT_CREDITS | Недостаточно кредитов |
429 |
RATE_LIMIT_EXCEEDED | Слишком много запросов |
По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.