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

Artigo para Voz (ATS)

Converta um artigo completo em áudio narrado e uma transcrição, entregues de forma assíncrona na sua URL de callback.

POST https://api.moknah.io/process-text

O endpoint de Artigo para Voz (ATS) recebe o texto de um artigo e gera uma narração em MP3 junto com um arquivo de transcrição sincronizada (.srt). A geração é assíncrona: a requisição retorna imediatamente com 202 Accepted e os arquivos prontos são entregues na callbackURL informada. Este é o mesmo serviço usado pelo plugin ATS para WordPress.

Assíncrono por definição

Não aguarde o áudio na resposta HTTP. O endpoint responde 202 imediatamente e envia o resultado via POST para a sua callbackURL quando a geração é concluída.

Autenticação

Inclua a chave de API da sua empresa como um token Bearer no cabeçalho Authorization.

Authorization: Bearer your_api_key

Corpo da requisição

Envie um corpo JSON com o texto puro do artigo e um objeto postData descrevendo a requisição.

Parâmetro Obrigatório Tipo Descrição
text obrigatório string O texto completo do artigo a ser convertido em fala.
postData obrigatório object Metadados da requisição. Veja os campos abaixo.

Objeto postData

Campo Obrigatório Tipo Padrão Descrição
name obrigatório string — Título do artigo. Usado como título da requisição de áudio gerado.
articleId obrigatório string — Seu identificador único para o artigo. Funciona como chave de idempotência (veja Idempotência abaixo) e é retornado no callback.
voiceId obrigatório string — A voz usada na narração. Use um ID da lista de vozes. Use uma voz do tipo da chave de API da sua empresa: uma chave padrão usa vozes padrão (voice_engine = standard) e uma chave avançada, vozes avançadas (voice_engine = advanced). Você escolhe o tipo ao gerar a chave. Em ambos os casos, cada frase do arquivo .srt tem tempos palavra por palavra.
callbackURL obrigatório string (URL) — URL HTTPS para a qual a Moknah enviará via POST as URLs do áudio e da transcrição concluídos. O valor mais recente fica salvo para a empresa.
preprocessType opcional string "0" Modo de preparação do texto: "0" para nenhum (narrar literalmente) ou "2" para tashkeel árabe (a IA adiciona os sinais diacríticos e escreve os números por extenso; dobra o custo por caractere). Aceita string ou número. "2" está disponível apenas para árabe, e somente as frases em árabe são enviadas para a IA.
language opcional string "auto" Idioma do conteúdo: "auto" ou um código ISO 639-1, como "ar" ou "en". Com "auto", o preprocessType "2" só é usado quando o texto está em árabe; caso contrário, o artigo é narrado como "0" e cobrado uma única vez. Enviar "2" com um idioma diferente do árabe é recusado com 422 VALIDATION_ERROR.
regenerate opcional boolean false Quando true, força uma nova geração mesmo que este articleId já tenha sido gerado antes.

Exemplo de requisição

curl -X POST "https://api.moknah.io/process-text" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
    "postData": {
        "name": "AI is evolving fast",
        "articleId": "post-123",
        "voiceId": "12",
        "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
        "preprocessType": "0",
        "language": "auto",
        "regenerate": false
    }
  }'
import requests

response = requests.post(
    "https://api.moknah.io/process-text",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
        "postData": {
            "name": "AI is evolving fast",
            "articleId": "post-123",
            "voiceId": "12",
            "callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
            "preprocessType": "0",
            "language": "auto",
            "regenerate": False
        }
    }
)

# 202 Accepted — the audio is delivered to your callbackURL
print(response.status_code, response.text)
const response = await fetch(
    'https://api.moknah.io/process-text',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.',
            postData: {
                name: 'AI is evolving fast',
                articleId: 'post-123',
                voiceId: '12',
                callbackURL: 'https://your-site.com/wp-json/ats/v1/callback',
                preprocessType: '0',
                language: 'auto',
                regenerate: false
            }
        })
    }
);

// 202 Accepted — result arrives at your callbackURL

Resposta imediata

Se a requisição for aceita, o endpoint responde imediatamente:

Processing started. Results will be sent to the callback URL.

Payload do callback

Quando a geração termina, a Moknah envia uma requisição POST para a sua callbackURL com este corpo JSON:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}
Campo Descrição
articleId O mesmo articleId que você enviou na requisição.
response.audioFile URL pública da narração em MP3 gerada, ou null se a geração falhar.
response.srtFile URL pública do arquivo de transcrição sincronizada (.srt), ou null se a geração falhar.
response.signature Assinatura HMAC-SHA256 que você pode usar para verificar se o payload é autêntico (veja abaixo).
Lidar com falhas na geração

Um callback também é enviado quando a geração não produz áudio. Nesse caso, response.audioFile e response.srtFile são null (a assinatura ainda cobre articleId|null|null). Trate qualquer callback cujo audioFile ou srtFile seja null como uma falha: não marque o artigo como concluído e reenvie-o com regenerate definido como true.

Verificando a assinatura

A assinatura é um HMAC-SHA256 (hex) da string articleId|audioFile|srtFile, usando como chave o digest hex SHA-256 da sua chave de API. Recalcule-a do seu lado e compare para confirmar que o callback veio da Moknah e não foi adulterado.

import crypto from 'crypto';

const keyHash = crypto.createHash('sha256').update(API_KEY).digest('hex');
const payload = `${articleId}|${audioFile}|${srtFile}`;
const expected = crypto.createHmac('sha256', keyHash).update(payload).digest('hex');

const isValid = expected === signature;
import hashlib, hmac

key_hash = hashlib.sha256(API_KEY.encode()).hexdigest()
payload = f"{article_id}|{audio_file}|{srt_file}"
expected = hmac.new(key_hash.encode(), payload.encode(), hashlib.sha256).hexdigest()

is_valid = hmac.compare_digest(expected, signature)

Idempotência e regeneração

  • As requisições são identificadas por articleId para cada empresa. Um novo articleId inicia uma nova geração.
  • Se um artigo estiver sendo gerado no momento, requisições repetidas serão rejeitadas com 409 ALREADY_PROCESSING.
  • Se um artigo já foi gerado e regenerate for false, o áudio existente será reenviado para o seu callbackURL sem gerar novamente (e sem nova cobrança).
  • Defina regenerate como true para forçar uma geração totalmente nova para um articleId existente.
  • Se uma tentativa anterior para um articleId falhou, enviá-lo de novo o gera novamente; não é preciso um novo articleId.

Concorrência e taxa de processamento

Os artigos são gerados a partir de uma fila em que cada cliente recebe uma parte justa. Você pode enviar muitos artigos de uma vez: todos são aceitos, gerados alguns de cada vez, e cada um é entregue à sua URL de callback assim que fica pronto.

  • Por isso, um lote grande é concluído aos poucos, e não todo de uma vez; não é preciso segurar artigos do seu lado.
  • Tente novamente qualquer artigo que falhou com regenerate definido como true; artigos já gerados ficam em cache e não precisam ser reenviados.
  • O endpoint /process-text também possui limite de taxa por cliente; picos acima do limite recebem 429 Too Many Requests, portanto espace ou envie suas requisições em lotes.

Faturamento

O custo em caracteres é calculado pelo número de caracteres em text multiplicado pelo fator de pré-processamento (1 por padrão, 2 quando preprocessType é 2). Os créditos só são descontados quando a geração realmente é executada. O reenvio de um artigo já gerado é gratuito e, se a geração ou a entrega falhar, os créditos descontados são reembolsados automaticamente.

Vozes avançadas (voice_engine = advanced) são cobradas pela tarifa do modo avançado, além do fator de pré-processamento.

Erros

Status Código Descrição
401 AUTH_FAILED Cabeçalho Authorization ausente ou chave de API inválida.
422 VALIDATION_ERROR Texto ausente ou campos de postData inválidos/ausentes.
400 INVALID_VOICE_ID O voiceId informado não existe.
400 UNSUPPORTED_VOICE A voz não é do tipo da sua chave de API (padrão ou avançada) ou não está disponível no momento.
409 ALREADY_PROCESSING Este artigo já está sendo gerado. Tente novamente após a conclusão.
422 PROCESSING_ERROR Falha na geração. Os créditos descontados serão reembolsados.
422 REFUND_FAILED O processamento falhou e o reembolso automático não foi concluído. Entre em contato com api@moknah.io.
Suporte da API

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