建立翻譯任務
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/json| 欄位 | 類型 | 必填 | 預設 | 說明 |
|---|---|---|---|---|
document_id | 字串 | ✅ | — | 已確認的文件 ID |
target_lang | 字串 | ✅ | — | 目標語言代碼 |
source_lang | 字串 | — | 自動檢測 | 原始語言代碼 |
engine | 字串 | — | xr-397b | 翻譯配置 ID,見 翻譯配置 |
output_mode | 字串 | — | bilingual | single 或 bilingual |
glossary_id | 字串 | — | — | 本帳戶術語表 ID。術語表僅向付費帳戶開放(帳戶曾有一次成功付款),未付費帳戶傳入會回傳 403 |
include_images | 布林值 | — | false | 是否處理文檔中的圖片文字 |
context_translation | 布林值 | — | false | 是否啟用上下文增強 |
style_preset | 字串 | — | — | 文風預設 |
任務建立後會進入佇列。每個帳號同時最多處理 5 個檔案,超過數量的任務仍可照常建立並自動排隊,待有任務完成後將依序開始;佇列中的任務 stage_message 會顯示前面還有幾個。
開始前按門檻檢查餘額:PDF 需餘額高於「頁數 × 2 积分」,其他格式按原文字數,最少 2 积分。餘額不足以開始某個檔案時,該任務以 status=failed、quota_exceeded=true 結束,不扣費,其他任務不受影響。完成後按實際用量扣費;實際費用超過餘額時餘額會變為負數,之後到账的積分先抵扣欠款,餘額為負時新任務無法開始,請充值。詳見 積分與用量 。
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"}'回應 201:
{ "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"}| 狀態 | 原因 |
|---|---|
403 | Key 不允許所選配置,或未付費帳號傳入了 glossary_id |
404 | 文件或術語表不存在、已刪除或不屬於本帳號 |
415 | 文件格式不支援翻譯 |
422 | 檔案為空、沒有可翻譯的文字,或參數無效 |
429 | 請求過於頻繁,或排隊中的任務已達上限,請按 Retry-After 重試 |
Idempotency-Key 為選填,建議每次提交時都攜帶。鍵為 1–128 個可見 ASCII 字元,在同一憑證下長期有效:
- 相同鍵、相同請求體:返回原任務(包括已失敗的任務),不會重複建立或扣費。
- 相同鍵、不同請求體:回傳
409(idempotency_request_conflict)。 - 原始任務已刪除:返回
410(idempotency_job_gone)。
每次新的提交使用新的 UUID,只在重試同一次提交時沿用原來的鍵。