Create a translation job
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/jsonRequest
Section titled “Request”| Field | Type | Required | Default | Description |
|---|---|---|---|---|
document_id | string | ✅ | — | ID of a confirmed document |
target_lang | string | ✅ | — | Target language code |
source_lang | string | — | Auto-detect | Source language code |
engine | string | — | xr-397b | Translation setting ID, see translation settings |
output_mode | string | — | bilingual | single or bilingual |
glossary_id | string | — | — | 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_images | boolean | — | false | Also translate text in the document’s images |
context_translation | boolean | — | false | Turn on context enhancement |
style_preset | string | — | — | 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.
Example
Section titled “Example”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"}Errors
Section titled “Errors”| Status | Cause |
|---|---|
403 | The key does not allow the chosen setting, or an unpaid account sent glossary_id |
404 | The document or glossary does not exist, was deleted or belongs to another account |
415 | The file format cannot be translated |
422 | The file is empty, has no translatable text, or a parameter is invalid |
429 | Too many requests, or the queue is full; retry after Retry-After |
Idempotency
Section titled “Idempotency”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.