Crea un lavoro di traduzione
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/jsonRichiesta
Sezione intitolata “Richiesta”| Campo | Tipo | Obbligatorio | Predefinito | Descrizione |
|---|---|---|---|---|
document_id | stringa | ✅ | — | ID di un documento confermato |
target_lang | stringa | ✅ | — | Codice della lingua di destinazione |
source_lang | stringa | — | Rilevamento automatico | Codice della lingua di origine |
engine | stringa | — | xr-397b | ID dell’impostazione di traduzione, vedi impostazioni di traduzione |
output_mode | stringa | — | bilingual | single o bilingual |
glossary_id | stringa | — | — | Un ID glossario di questo account. I glossari sono destinati agli account paganti (almeno un pagamento riuscito); un account non pagato che ne invia uno riceve 403 |
include_images | boolean | — | false | Traduci anche il testo presente nelle immagini del documento. |
context_translation | boolean | — | false | Attiva il miglioramento del contesto |
style_preset | stringa | — | — | Preimpostazione di stile |
Un lavoro creato entra nella coda. Ogni account elabora fino a 5 file contemporaneamente; ulteriori lavori vengono comunque creati e inseriti automaticamente in coda, avviandosi man mano che quelli precedenti terminano. Mentre un lavoro è in attesa, il suo stage_message indica quanti lavori lo precedono.
Prima dell’inizio di un lavoro, il saldo viene verificato rispetto a una soglia: un PDF richiede un saldo superiore a “pagine × 2 crediti”; altri formati si basano sulla lunghezza del testo di origine, con un minimo di 2 crediti. Se il saldo non consente l’avvio di un file, tale lavoro termina con status=failed e quota_exceeded=true, non viene addebitato alcun importo e gli altri lavori non sono influenzati. Al termine di un lavoro, viene addebitato l’utilizzo effettivo; se il costo supera il saldo, questo diventa negativo, i crediti successivi saldano prima il debito e, finché il saldo è negativo, non è possibile avviare nuovi lavori, quindi è necessario ricaricare il credito. Vedere crediti e utilizzo .
Esempio
Sezione intitolata “Esempio”curl --fail-with-body -X POST https://omnidoc.top/api/v1/jobs \ -H "X-API-Key: $OMNIDOC_API_KEY" \ -H "Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f" \ -H "Content-Type: application/json" \ -d '{"document_id":"4q8mx2q9z1k7p6ra","target_lang":"en"}'Risposta 201 (il stage_message del server è in cinese):
{ "id": "q3f8s6c2a9m1k4tx", "document_id": "4q8mx2q9z1k7p6ra", "source_lang": null, "target_lang": "en", "engine": "xr-397b", "status": "pending", "stage": "queued", "stage_progress": 0, "stage_message": "排队中", "time_cost": 0, "error_msg": null, "quota_exceeded": false, "queue_position": null, "created_at": "2026-10-01T12:01:00Z", "updated_at": "2026-10-01T12:01:00Z"}| Stato | Causa |
|---|---|
403 | La chiave non consente l’impostazione selezionata, oppure un account non pagato ha inviato glossary_id |
404 | Il documento o il glossario non esiste, è stato eliminato oppure appartiene a un altro account |
415 | Il formato del file non può essere tradotto |
422 | Il file è vuoto, non contiene testo traducibile o un parametro è invalido |
429 | Troppe richieste o la coda è piena; riprova dopo Retry-After |
Idempotenza
Sezione intitolata “Idempotenza”Idempotency-Key è facoltativo ma consigliato per ogni invio. Una chiave è composta da 1–128 caratteri ASCII visibili e rimane valida a tempo indeterminato per lo stesso credenziale:
- Stessa chiave, stesso corpo: restituisce l’operazione originale (inclusa quella fallita); nulla viene creato o addebitato due volte.
- Stessa chiave, corpo diverso:
409(idempotency_request_conflict). - Il lavoro originale è stato eliminato:
410(idempotency_job_gone).
Utilizzare una nuova UUID per ogni nuovo invio e riutilizzare la chiave originale solo quando si ripete lo stesso invio.