跳到內容

建立翻譯任務

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
欄位類型必填預設說明
document_id字串✅—已確認的文件 ID
target_lang字串✅—目標語言代碼
source_lang字串—自動檢測原始語言代碼
engine字串—xr-397b翻譯配置 ID,見 翻譯配置
output_mode字串—bilingualsingle 或 bilingual
glossary_id字串——本帳戶術語表 ID。術語表僅向付費帳戶開放(帳戶曾有一次成功付款),未付費帳戶傳入會回傳 403
include_images布林值—false是否處理文檔中的圖片文字
context_translation布林值—false是否啟用上下文增強
style_preset字串——文風預設

任務建立後會進入佇列。每個帳號同時最多處理 5 個檔案,超過數量的任務仍可照常建立並自動排隊,待有任務完成後將依序開始;佇列中的任務 stage_message 會顯示前面還有幾個。

開始前按門檻檢查餘額:PDF 需餘額高於「頁數 × 2 积分」,其他格式按原文字數,最少 2 积分。餘額不足以開始某個檔案時,該任務以 status=failed、quota_exceeded=true 結束,不扣費,其他任務不受影響。完成後按實際用量扣費;實際費用超過餘額時餘額會變為負數,之後到账的積分先抵扣欠款,餘額為負時新任務無法開始,請充值。詳見 積分與用量 。

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

回應 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"
}
狀態原因
403Key 不允許所選配置,或未付費帳號傳入了 glossary_id
404文件或術語表不存在、已刪除或不屬於本帳號
415文件格式不支援翻譯
422檔案為空、沒有可翻譯的文字,或參數無效
429請求過於頻繁,或排隊中的任務已達上限,請按 Retry-After 重試

Idempotency-Key 為選填,建議每次提交時都攜帶。鍵為 1–128 個可見 ASCII 字元,在同一憑證下長期有效:

  • 相同鍵、相同請求體:返回原任務(包括已失敗的任務),不會重複建立或扣費。
  • 相同鍵、不同請求體:回傳 409(idempotency_request_conflict)。
  • 原始任務已刪除:返回 410(idempotency_job_gone)。

每次新的提交使用新的 UUID,只在重試同一次提交時沿用原來的鍵。