Texto a voz (TTS)
Convierte texto en voz de sonido natural
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 |
Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.