文档翻译 API 接入指南：用 Python 批量翻译 Word、PDF，并用 Webhook 接收结果

文档翻译 API 接入指南：用 Python 批量翻译 Word、PDF，并用 Webhook 接收结果 如果你的系统每天要处理合同、说明书、论文或报表，手动上传、等待、下载很快就会变成瓶颈。OmniDoc（至译）的文档翻译 API 把整个流程交给程序： 上传文件、创建任务、接收完成通知、下载译文 ，译文保留原文件的版式、表格、图片和公式，可输出双语对照或仅译文。 基本信息 表 1 API 基本约定 项目 说明 Base URL https://omnidoc.top/api/v1 认证 API Key 放在 X-API-Key 请求头，也可作为 Bearer 凭据发送；在 API 控制台创建 请求格式 JSON，Content-Type: application/json 请求追踪 保存每次响应的 X-Request-Id，联系支持时提供 限流 返回 429 时按 Retry-After 重试 支持哪些文件 Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）、PDF、HTML、EPUB、Markdown 与文本、SRT/ASS 字幕、CSV、PNG/JPG 图片和 UniDoc 文档（.udoc）。除 PPTX 外都支持双语输出：Word 按段落对照，Excel 按列对照，PDF 按页面对照，字幕按行对照；PPTX 请求双语时返回仅译文。 四步完成一次翻译 申请上传 ：POST /upload/presign，提交文件名和大小，拿到直传地址、上传头和 finalize_token。 上传并确认 ：用返回的上传头 PUT 文件（不要带 API Key），再 POST /upload/finalize 换取 document.id。 创建任务 ：POST /jobs，提交 document_id 和 target_lang，建议带 Idempotency-Key。 取回结果 ：轮询 GET /jobs/{id}，或订阅 SSE 进度、配置 Webhook；完成后用 GET /artifacts?job_id=... 获取产物并下载。 创建任务的常用参数 表 2 POST /jobs 请求字段 字段 默认 说明 document_id — 已确认的文档 ID（必填） target_lang — 目标语言代码（必填） source_lang 自动检测 源语言代码 engine xr-397b 翻译配置：xr-397b、deepseek、qwen、chatgpt、gemini、claude output_mode bilingual bilingual 双语对照，single 仅译文 glossary_id — 术语表 ID，统一品牌名和专业词 include_images false 是否处理文档中的图片文字 context_translation false 上下文增强，前后术语更一致 style_preset — 文风预设 Python 示例：创建任务并等待完成 下面的片段只依赖 requests。完整的上传与下载流程见开发者文档的 Python 页面。 import time, uuid, requests BASE = "https://omnidoc.top/api/v1" HEADERS = {"X-API-Key": "sk_your_key"} def create_job(document_id, target_lang="en", engine="xr-397b"): r = requests.post(f"{BASE}/jobs", headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())}, json={"document_id": document_id, "target_lang": target_lang, "engine": engine}, timeout=30) r.raise_for_status() return r.json() def wait_for_job(job_id): while True: job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=20).json() if job["status"] in ("completed", "failed"): return job time.sleep(5) 批量与重试：并发、排队和幂等 自动排队 ：每个账号同时处理最多 5 个文件，更多任务照常创建并排队，stage_message 会说明前面还有几个。 幂等键 ：相同 Idempotency-Key、相同请求体会返回原任务，不会重复创建或重复扣费；网络超时时先查询状态，不要换新键重提。 错误码 ：403 表示 Key 不允许所选配置，404 表示文档或术语表不存在，415 表示格式不支持，422 表示文件为空或参数无效。 Webhook：任务结束时通知你的服务器 每个用户最多配置 3 个 Webhook（POST /webhooks 创建，PATCH 更新或停用）。文件翻译任务结束时（成功或失败）发送 job.completed 事件，data.status 为 completed 或 failed，data.char_count 为译文字符数。创建时填写 secret 后，每次回调都带 X-Webhook-Signature，用 HMAC-SHA256 对原始请求体验签即可确认来源。URL 必须可从公网访问，建议使用 HTTPS。 费用怎么算 开始前检查门槛 ：PDF 需余额高于“页数 × 2 积分”，其他格式按原文字数，最少 2 积分；不足时任务以 quota_exceeded 结束，不扣费。 完成后按实际用量扣费 ；任务失败或取消不扣费。 查询免费 ：余额、任务状态、用量、凭证和下载地址都不扣积分。 积分包 ：3,000 积分 ¥9.9 起，购买的积分长期有效；在售套餐可用 GET /billing/credits/plans 查询。 下一步 开发者文档：https://docs.omnidoc.top/guide/quickstart/ （cURL、Python、Node.js 三种完整示例）。不想写代码？接入 OmniDoc 的 AI 助手也能直接翻译本机文件，见《让 AI 直接操作 Word、Excel 和 PPT》：https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/ 。 - 1 -