Moknah Documenti
Inizia gratis
Riferimento API

Da Articolo a Voce (ATS)

Converti un intero articolo in audio narrato e una trascrizione, inviati in modo asincrono al tuo URL di callback.

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

L'endpoint da Articolo a Voce (ATS) accetta il testo di un articolo e genera una narrazione MP3 insieme a un file di trascrizione sincronizzata (.srt). La generazione avviene in modo asincrono: la richiesta restituisce immediatamente 202 Accepted e i file completati vengono inviati al callbackURL fornito. Questo è lo stesso servizio su cui si basa il plugin WordPress ATS.

Asincrono per progettazione

Non attendere l'audio nella risposta HTTP. L'endpoint risponde subito con 202 e invia il risultato tramite POST al tuo callbackURL al termine della generazione.

Autenticazione

Includi la chiave API aziendale come token Bearer nell'intestazione Authorization.

Authorization: Bearer your_api_key

Corpo della richiesta

Invia un corpo JSON con il testo grezzo dell'articolo e un oggetto postData che descrive la richiesta.

Parametro Obbligatorio Tipo Descrizione
text obbligatorio string Il testo completo dell'articolo da convertire in voce.
postData obbligatorio object Metadati della richiesta. Vedi i campi qui sotto.

Oggetto postData

Campo Obbligatorio Tipo Predefinito Descrizione
name obbligatorio string — Titolo dell'articolo. Usato come titolo della richiesta audio generata.
articleId obbligatorio string — Il tuo identificatore univoco per l'articolo. Funge da chiave di idempotenza (vedi Idempotenza più avanti) e viene restituito nel callback.
voiceId obbligatorio string — La voce con cui narrare. Usa un ID dalla lista delle voci. Usa una voce del tipo della chiave API della tua azienda: una chiave standard usa voci standard (voice_engine = standard), una chiave avanzata voci avanzate (voice_engine = advanced). Il tipo si sceglie quando generi la chiave. In entrambi i casi ogni frase del file .srt ha i tempi parola per parola.
callbackURL obbligatorio string (URL) — URL HTTPS a cui Moknah invierà tramite POST gli URL dell'audio e della trascrizione completati. L'ultimo valore viene memorizzato per l'azienda.
preprocessType opzionale string "0" Modalità di preparazione del testo: "0" per nessuna (narrazione letterale) o "2" per il tashkeel arabo (l’IA aggiunge i segni diacritici e scrive i numeri in lettere; raddoppia il costo per carattere). Accettata come stringa o come numero. "2" è disponibile solo per l’arabo, e all’IA vengono inviate solo le frasi in arabo.
language opzionale string "auto" Lingua del contenuto: "auto" oppure un codice ISO 639-1 come "ar" o "en". Con "auto", preprocessType "2" viene usato solo se il testo è in arabo; altrimenti l’articolo viene narrato come "0" e addebitato una sola volta. L’invio di "2" con una lingua diversa dall’arabo viene rifiutato con 422 VALIDATION_ERROR.
regenerate opzionale boolean false Quando è true, forza una nuova generazione anche se questo articleId è già stato generato in precedenza.

Esempio di richiesta

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

Risposta immediata

Se la richiesta viene accettata, l'endpoint risponde immediatamente:

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

Payload del callback

Al termine della generazione, Moknah invia una richiesta POST al tuo callbackURL con questo 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 Descrizione
articleId Lo stesso articleId che hai inviato nella richiesta.
response.audioFile URL pubblico della narrazione MP3 generata, oppure null se la generazione è fallita.
response.srtFile URL pubblico del file di trascrizione sincronizzata (.srt), oppure null se la generazione è fallita.
response.signature Firma HMAC-SHA256 che puoi usare per verificare l'autenticità del payload (vedi sotto).
Gestire le generazioni fallite

Viene inviato un callback anche quando la generazione non produce alcun audio. In tal caso response.audioFile e response.srtFile sono null (la firma copre comunque articleId|null|null). Considera qualsiasi callback in cui audioFile o srtFile è null come un errore: non contrassegnare l'articolo come completato e invialo di nuovo impostando regenerate su true.

Verifica della firma

La firma è un HMAC-SHA256 (esadecimale) della stringa articleId|audioFile|srtFile, con chiave basata sul digest esadecimale SHA-256 della tua chiave API. Ricalcolala dal tuo lato e confrontala per confermare che il callback provenga da Moknah e non sia stato manomesso.

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)

Idempotenza e rigenerazione

  • Le richieste sono identificate tramite articleId per ciascuna azienda. Un nuovo articleId avvia una nuova generazione.
  • Se un articolo è attualmente in fase di generazione, le richieste ripetute vengono rifiutate con 409 ALREADY_PROCESSING.
  • Se un articolo è già stato generato e regenerate è false, l'audio esistente viene inviato nuovamente al tuo callbackURL senza rigenerarlo (e senza alcun costo aggiuntivo).
  • Imposta regenerate su true per forzare una generazione completamente nuova per un articleId esistente.
  • Se un tentativo precedente per un articleId non è riuscito, inviarlo di nuovo lo genera da capo; non serve un nuovo articleId.

Concorrenza e throughput

Gli articoli vengono generati da una coda in cui ogni cliente ha una quota equa. Puoi inviare molti articoli insieme: vengono tutti accettati, generati pochi alla volta e ciascuno viene consegnato al tuo URL di callback appena è pronto.

  • Un lotto grande quindi si completa gradualmente e non tutto insieme; non serve trattenere gli articoli dalla tua parte.
  • Riprova qualsiasi articolo fallito impostando regenerate su true; gli articoli già generati vengono salvati nella cache e non devono essere inviati di nuovo.
  • Anche l'endpoint /process-text è soggetto a rate limit per cliente; i picchi che superano il limite ricevono l'errore 429 Too Many Requests, quindi distanzia o raggruppa i tuoi invii.

Fatturazione

Il costo in caratteri è calcolato come il numero di caratteri in text moltiplicato per il fattore di pre-elaborazione (1 per impostazione predefinita, 2 quando preprocessType è 2). I crediti vengono scalati solo quando la generazione viene effettivamente eseguita. La riconsegna di un articolo già generato è gratuita e, se la generazione o la consegna non va a buon fine, i crediti scalati vengono rimborsati automaticamente.

Le voci avanzate (voice_engine = advanced) sono addebitate alla tariffa della modalità avanzata, oltre al fattore di pre-elaborazione.

Errori

Stato Codice Descrizione
401 AUTH_FAILED Header Authorization mancante o chiave API non valida.
422 VALIDATION_ERROR Testo mancante o campi postData non validi/mancanti.
400 INVALID_VOICE_ID Il voiceId fornito non esiste.
400 UNSUPPORTED_VOICE La voce non è del tipo della tua chiave API (standard o avanzata) oppure non è disponibile al momento.
409 ALREADY_PROCESSING Questo articolo è già in fase di generazione. Riprova al termine.
422 PROCESSING_ERROR Generazione non riuscita. Eventuali crediti scalati vengono rimborsati.
422 REFUND_FAILED L'elaborazione non è riuscita e il rimborso automatico non è stato completato. Contatta api@moknah.io.
Supporto API

Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.