Moknah Documentação
Comece grátis
Referência da API

Texto para Voz (TTS)

Converta texto em fala com som natural

POST /api/v1/tts/generate/

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
Suporte da API

Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.