Skip to content

Create a translation job

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
FieldTypeRequiredDefaultDescription
document_idstring✅—ID of a confirmed document
target_langstring✅—Target language code
source_langstring—Auto-detectSource language code
enginestring—xr-397bTranslation setting ID, see translation settings
output_modestring—bilingualsingle or bilingual
glossary_idstring——A glossary ID of this account. Glossaries are for paying accounts (at least one successful payment); an unpaid account that sends one gets 403
include_imagesboolean—falseAlso translate text in the document’s images
context_translationboolean—falseTurn on context enhancement
style_presetstring——Style preset

A created job enters the queue. Each account processes up to 5 files at a time; further jobs are still created and queue automatically, starting as earlier ones finish. While a job waits, its stage_message says how many jobs are ahead.

Before a job starts, the balance is checked against a threshold: a PDF needs a balance above “pages × 2 credits”; other formats go by the length of the source text, at least 2 credits. If the balance cannot start a file, that job ends with status=failed and quota_exceeded=true, nothing is charged, and other jobs are not affected. When a job finishes, the actual usage is charged; if the cost exceeds the balance, the balance goes negative, credits that arrive later pay off the debt first, and new jobs cannot start while the balance is negative, so top up. See credits and usage.

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"}'

Response 201 (the server’s stage_message is in Chinese):

{
"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"
}
StatusCause
403The key does not allow the chosen setting, or an unpaid account sent glossary_id
404The document or glossary does not exist, was deleted or belongs to another account
415The file format cannot be translated
422The file is empty, has no translatable text, or a parameter is invalid
429Too many requests, or the queue is full; retry after Retry-After

Idempotency-Key is optional but recommended for every submission. A key is 1–128 visible ASCII characters and stays valid indefinitely for the same credential:

  • Same key, same body: returns the original job (including a failed one); nothing is created or charged twice.
  • Same key, different body: 409 (idempotency_request_conflict).
  • The original job was deleted: 410 (idempotency_job_gone).

Use a new UUID for each new submission, and reuse the original key only when retrying that same submission.