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.
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.
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). |
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. |
Para dúvidas ou problemas relacionados à API, entre em contato conosco em api@moknah.io.