Salta ai contenuti

Crea un lavoro di traduzione

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
CampoTipoObbligatorioPredefinitoDescrizione
document_idstringa✅—ID di un documento confermato
target_langstringa✅—Codice della lingua di destinazione
source_langstringa—Rilevamento automaticoCodice della lingua di origine
enginestringa—xr-397bID dell’impostazione di traduzione, vedi impostazioni di traduzione
output_modestringa—bilingualsingle o bilingual
glossary_idstringa——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_imagesboolean—falseTraduci anche il testo presente nelle immagini del documento.
context_translationboolean—falseAttiva il miglioramento del contesto
style_presetstringa——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 .

Terminal window
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"
}
StatoCausa
403La chiave non consente l’impostazione selezionata, oppure un account non pagato ha inviato glossary_id
404Il documento o il glossario non esiste, è stato eliminato oppure appartiene a un altro account
415Il formato del file non può essere tradotto
422Il file è vuoto, non contiene testo traducibile o un parametro è invalido
429Troppe richieste o la coda è piena; riprova dopo Retry-After

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.