Texto para Voz (TTS)
Converta texto em fala com som natural
Converta texto em fala usando síntese de voz por IA. Retorna um arquivo de áudio MP3.
Autenticação
Inclua sua chave de API no cabeçalho Authorization.
Corpo da requisição
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| text | obrigatório | string | Texto a converter (máx. de 1500 caracteres) |
| output_format | opcional | string | Formato de saída de áudio desejado. Especificado como codec_sampleRate_bitrate (ex.: mp3_22050_32). O padrão é mp3_44100_128. Veja a seção Formatos de saída abaixo para a lista completa. |
| voice_id | obrigatório | inteiro | ID da voz da lista de vozes. |
| prerecording | opcional | inteiro | 1 ( Aprimoramento básico), 2 (Aprimoramento por IA / Tashkeel árabe) ou 3 (Poeta IA). 2 e 3 estão disponíveis apenas para conteúdo em árabe; veja language. |
| language | opcional | string | Idioma do conteúdo como código ISO 639-1, por exemplo ar ou en (códigos de região como ar-JO são aceitos). Define quais modos de pré-gravação são permitidos e não é enviado para a voz. Os modos 2 e 3 estão disponíveis apenas para árabe (ar). Se language for omitido, 2 e 3 implicam árabe, para que as integrações existentes continuem funcionando. Qualquer outro idioma com 2 ou 3, ou um código desconhecido, retorna 400 INVALID_REQUEST com o motivo em details.language. |
| voice_settings | opcional | string (JSON) | Opções de personalização de voz |
Formatos de saída suportados
O parâmetro output_format pode receber qualquer um dos seguintes 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 da própria saída do motor (sem perdas). Não disponível no WebSocket de streaming; use pcm_* lá.
Esta seção serve como referência para que os usuários possam selecionar o formato apropriado sem sobrecarregar a tabela principal de requisição.
Motores e modos
Cada voz pertence a um de dois motores. A lista de vozes retorna isso como voice_engine, e a voz que você escolher define quais configurações se aplicam.
Cada chave de API é para um motor: padrão (o padrão) ou avançado, escolhido ao criar a chave. A chave lista e usa só as vozes do seu motor; crie uma segunda chave para usar o outro.
- Motor Padrão (
standard) — vozes de estúdio com três modos que equilibram velocidade, expressividade e preço. - Motor Avançado (
advanced, alfa) — suas próprias vozes, direcionadas em linguagem natural com context, setting, style e pace. Os modos não se aplicam.
Modos do motor Padrão
| mode | Nome | Créditos | Ideal para |
|---|---|---|---|
emotion padrão |
Emoção e dialeto | ×1 | Fala rápida e expressiva com emoções e dialetos. Compatível com tags de emoção como [laughing] e [whispering]. |
quality |
Emoção e dialeto de alta qualidade | ×2 | Emoções e dialetos mais ricos e naturais. Leva um pouco mais de tempo. Compatível com tags de emoção. |
studio |
Qualidade de estúdio | ×2 | Narração de estúdio limpa e consistente com controle total da voz. Sem tags de emoção. |
Solicitações sem um mode são executadas no modo emotion.
Objeto de configurações de voz
Vozes do mecanismo Padrão
| Parâmetro | Tipo | Intervalo | Padrão | Descrição |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Modo do mecanismo Padrão. quality e studio custam ×2 créditos. Veja Mecanismos e modos acima. |
| temperature | inteiro | 0 – 100 | 25 | Controla a variabilidade e a expressividade da fala. Valores mais baixos produzem uma fala mais estável e previsível, enquanto valores mais altos aumentam a variação, a espontaneidade e o fraseado criativo. |
| voice_similarity | inteiro | 0 – 100 | 100 | Determina o quão próxima a fala gerada fica do perfil de voz selecionado. Valores mais altos preservam a identidade original da voz, enquanto valores mais baixos permitem maior variação no tom e na articulação. |
| speed | float | 0.7 – 1.2 | 1.0 | Ajusta a velocidade da fala. Valores abaixo de 1.0 desaceleram a fala para maior clareza, enquanto valores acima de 1.0 aumentam a velocidade. Apenas no modo studio; ignorado em emotion e quality. |
| enable_emotions obsoleto | boolean | false / true | — | Ainda aceito para compatibilidade, mas não altera mais o resultado. Use mode em vez disso. |
| fast_mode obsoleto | inteiro | 0, 1, or 2 | — | Ainda aceito para compatibilidade, mas não altera mais o resultado; o modo emotion já é a opção rápida. Para áudio em tempo real, use o endpoint de streaming. |
Nos modos emotion e quality, temperature e voice_similarity são os controles de voz (qualquer valor dentro do intervalo é usado como está); speed aplica-se apenas ao modo studio.
Vozes do mecanismo Avançado
| Parâmetro | Tipo | Valores | Descrição |
|---|---|---|---|
| context | string | até 500 caracteres | O controle mais forte. Descreva sotaque, sentimento, humor ou propósito, ex.: “Uma leitura de documentário calorosa em dialeto levantino.” |
| setting | string | até 500 caracteres | Cena e ambiente, ex.: “Um estúdio noturno calmo e intimista.” |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Estilo geral de locução. |
| pace | string | slow, normal, fast | Ritmo da fala. |
As vozes do mecanismo Avançado ignoram mode e os controles deslizantes do mecanismo Padrão, e retornam o output_format solicitado. A geração pode levar um pouco mais de tempo do que no mecanismo Padrão.
Regras e restrições das configurações de voz
- Chaves desconhecidas, um mode, style ou pace inválido, ou um context/setting com mais de 500 caracteres são rejeitados com 400 INVALID_REQUEST.
-
Para compatibilidade, quando o parâmetro obsoleto enable_emotions for true, os seguintes campos não devem ser incluídos em voice_settings:
speed,fast_mode.
Preços
Créditos = caracteres × (taxa de pré-gravação + taxa de voz %) × multiplicador de modo. O multiplicador é ×2 para quality e studio, ×1 para emotion e ×1.5 para cada voz do mecanismo Avançado.
Exemplo
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
Resposta
Retorna dados de áudio binários no output_format solicitado (MP3 por padrão) com estes cabeçalhos:
| Cabeçalho | Descrição |
|---|---|
Content-Type |
Corresponde a 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, sem cabeçalho). |
Erros
| Status | Código | Descrição |
|---|---|---|
400 |
INVALID_REQUEST | Parâmetros inválidos (incluindo mode, style ou pace desconhecidos) |
401 |
UNAUTHORIZED | Chave de API inválida |
402 |
INSUFFICIENT_CREDITS | Créditos insuficientes |
429 |
RATE_LIMIT_EXCEEDED | Muitas solicitações |
Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.