创建翻译任务

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json

请求

字段	类型	必填	默认	说明
`document_id`	string	✅	—	已确认的文档 ID
`target_lang`	string	✅	—	目标语言代码
`source_lang`	string	—	自动检测	源语言代码
`engine`	string	—	`xr-397b`	翻译配置 ID，见翻译配置
`output_mode`	string	—	`bilingual`	`single` 或 `bilingual`
`glossary_id`	string	—	—	本账号术语表 ID
`include_images`	boolean	—	`false`	是否处理文档中的图片文字
`context_translation`	boolean	—	`false`	是否启用上下文增强
`style_preset`	string	—	—	文风预设

任务创建后进入队列。每个账号同时处理最多 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 不允许所选配置，或文档不属于本账号
`404`	文档不存在或已删除
`415`	文件格式不支持翻译
`422`	文件为空、没有可翻译的文字，或参数无效
`429`	请求过于频繁，或排队中的任务已达上限，按 `Retry-After` 重试

幂等

Idempotency-Key 可选，建议每次提交都携带。键为 1–128 个可见 ASCII 字符，在同一凭据下长期有效：

相同键、相同请求体：返回原任务（包括已失败的任务），不会重复创建或扣费。
相同键、不同请求体：返回 409（idempotency_request_conflict）。
原任务已删除：返回 410（idempotency_job_gone）。

每次新的提交使用新的 UUID，只在重试同一次提交时沿用原来的键。