Da Articolo a Voce (ATS)
Converti un intero articolo in audio narrato e una trascrizione, inviati in modo asincrono al tuo URL di callback.
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.
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). |
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. |
Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.