Moknah Документы
Начать бесплатно
Справочник по API

Преобразование текста в речь (TTS)

Преобразуйте текст в естественную речь.

ПУБЛИКАЦИЯ /api/v1/tts/generate/

Преобразуйте текст в речь с помощью синтеза голоса на базе ИИ. Результатом является аудиофайл в формате 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, обращайтесь к нам по адресу api@moknah.io.