Moknah Documentación
Empieza gratis
Referencia de la API

Texto a voz (TTS)

Convierte texto en voz de sonido natural

POST /api/v1/tts/generate/

Convierte texto en voz mediante síntesis de voz con IA. Devuelve un archivo de audio MP3.

Autenticación

Incluye tu clave de API en el encabezado Authorization.

Cuerpo de la solicitud

Parámetro Obligatorio Tipo Descripción
text obligatorio string Texto a convertir (máx. 1500 caracteres)
output_format opcional string Formato de salida de audio deseado. Se especifica como codec_sampleRate_bitrate (p. ej., mp3_22050_32). El valor predeterminado es mp3_44100_128. Consulta la sección Formatos de salida a continuación para ver la lista completa.
voice_id obligatorio entero ID de voz de la lista de voces.
prerecording opcional entero 1 (Mejora básica), 2 (Mejora con IA / Tashkeel árabe) o 3 (Poeta IA). 2 y 3 solo están disponibles para contenido en árabe; consulta language.
language opcional string Idioma del contenido como código ISO 639-1, por ejemplo ar o en (se aceptan códigos de región como ar-JO). Determina qué modos de pregrabación están permitidos y no se envía a la voz. Los modos 2 y 3 solo están disponibles para árabe (ar). Si se omite language, 2 y 3 implican árabe, por lo que las integraciones existentes siguen funcionando. Cualquier otro idioma con 2 o 3, o un código desconocido, devuelve 400 INVALID_REQUEST con el motivo en details.language.
voice_settings opcional cadena (JSON) Opciones de personalización de la voz

Formatos de salida admitidos

El parámetro output_format puede tomar cualquiera de los siguientes valores:

  • 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: 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 — WAV mono de 16 bits de la salida directa del motor (sin pérdida). No disponible en el WebSocket de streaming; usa pcm_* allí.

Esta sección sirve como referencia para que los usuarios puedan seleccionar el formato adecuado sin saturar la tabla principal de la solicitud.

Motores y modos

Cada voz pertenece a uno de dos motores. La lista de voces lo devuelve como voice_engine, y la voz que elijas determina qué ajustes se aplican.

Cada clave API es para un motor: estándar (el predeterminado) o avanzado, elegido al crear la clave. Una clave solo lista y usa las voces de su motor; crea una segunda clave para usar el otro.

  • Motor Estándar (standard) — voces de estudio con tres modos que equilibran velocidad, expresividad y precio.
  • Motor Avanzado (advanced, alfa) — sus propias voces, dirigidas en lenguaje natural con context, setting, style y pace. Los modos no se aplican.

Modos del motor Estándar

mode Nombre Créditos Ideal para
emotion predeterminado Emoción y dialecto ×1 Voz rápida y expresiva con emociones y dialectos. Admite etiquetas de emoción como [laughing] y [whispering].
quality Emoción y dialecto de alta calidad ×2 Emociones y dialectos más ricos y naturales. Tarda un poco más. Admite etiquetas de emoción.
studio Calidad de estudio ×2 Narración de estudio limpia y uniforme con control total de la voz. Sin etiquetas de emoción.

Las solicitudes sin mode se ejecutan en modo emotion.

Objeto de configuración de voz

Voces del motor Estándar

Parámetro Tipo Rango Predeterminado Descripción
mode string emotion, quality, studio emotion Modo del motor Estándar. quality y studio cuestan ×2 créditos. Consulta Motores y modos más arriba.
temperature entero 0 – 100 25 Controla la variabilidad y expresividad del habla. Los valores más bajos producen un habla más estable y predecible, mientras que los más altos aumentan la variación, la espontaneidad y el fraseo creativo.
voice_similarity entero 0 – 100 100 Determina qué tan fielmente coincide el habla generada con el perfil de voz seleccionado. Los valores más altos preservan la identidad de la voz original, mientras que los más bajos permiten mayor desviación en el tono y la articulación.
speed float 0.7 – 1.2 1.0 Ajusta la velocidad del habla. Los valores inferiores a 1.0 reducen la velocidad para mayor claridad, mientras que los valores superiores a 1.0 la aumentan. Solo modo studio; se ignora en emotion y quality.
enable_emotions obsoleto boolean false / true — Se sigue aceptando por compatibilidad, pero ya no cambia el resultado. Usa mode en su lugar.
fast_mode obsoleto entero 0, 1, or 2 — Se sigue aceptando por compatibilidad, pero ya no cambia el resultado; el modo emotion ya es la opción rápida. Para audio en tiempo real, usa el endpoint de streaming.

En los modos emotion y quality, temperature y voice_similarity son los controles de voz (cualquier valor dentro del rango se usa tal cual); speed solo se aplica al modo studio.

Voces del motor Avanzado

Parámetro Tipo Valores Descripción
context string hasta 500 caracteres El control más potente. Describe el acento, sentimiento, estado de ánimo o propósito, p. ej., “Una lectura documental cálida en dialecto levantino”.
setting string hasta 500 caracteres Escena y ambiente, p. ej., “Un estudio nocturno tranquilo e íntimo”.
style string neutral, warm, energetic, serious, cheerful, poetic Estilo general de locución.
pace string slow, normal, fast Ritmo del habla.

Las voces del motor Avanzado ignoran mode y los controles deslizantes del motor Estándar, y devuelven el output_format solicitado. La generación puede tardar un poco más que con el motor Estándar.

Reglas y restricciones de configuración de voz

  • Las claves desconocidas, un mode, style o pace no válido, o un context/setting de más de 500 caracteres se rechazan con 400 INVALID_REQUEST.
  • Por compatibilidad, cuando el parámetro obsoleto enable_emotions es true, no deben incluirse los siguientes campos en voice_settings: speed, fast_mode.

Precios

Créditos = caracteres × (tarifa base + tarifa de voz %) × multiplicador de modo. El multiplicador es ×2 para quality y studio, ×1 para emotion y ×1.5 para cada voz del motor Avanzado.

Ejemplo

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

Respuesta

Devuelve datos de audio binarios en el output_format solicitado (MP3 por defecto) con estos encabezados:

Encabezado Descripción
Content-Type Coincide con output_format: audio/mpeg para mp3_*, audio/ogg para opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 para pcm_* (raw de 16 bits little-endian, sin encabezado).

Errores

Estado Código Descripción
400 INVALID_REQUEST Parámetros no válidos (incluidos un mode, style o pace desconocidos)
401 UNAUTHORIZED Clave de API no válida
402 INSUFFICIENT_CREDITS No hay suficientes créditos
429 RATE_LIMIT_EXCEEDED Demasiadas solicitudes
Soporte de API

Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.