文档翻译 API 怎么接入？与文本翻译 API 的区别及 Python 示例

如果你的产品要让用户上传一份 PDF、Word、Excel 或 PPT，再拿回可下载、可继续流转的译文文件，纯文本翻译 API 通常不够。文档翻译 API 处理的不只是句子，而是文件上传、格式解析、异步任务、失败重试、结果下载和交付复核组成的完整流程。

本文先说明文档翻译 API 与文本翻译 API 的区别，再给出一套可以落到后台服务和任务队列中的接入方式。示例按当前公开接口编写，支持 PDF、DOCX、PPTX 和 XLSX。

文档翻译 API 与文本翻译 API 有什么区别？

两类接口并不是互相替代。已经有成熟文档解析和重建能力的团队，可以继续使用文本 API；希望直接接入“文档进、结果文件出”流程的团队，更适合使用文档翻译 API。

一个可靠的异步文档翻译流程

1. 服务端接收文件：不要把 API Key 放进浏览器前端。由自己的后端、任务进程或受控自动化环境调用接口。
2. 创建业务幂等键：每次业务操作生成一个 Idempotency-Key，用于保护结果未知时的安全重试。
3. 上传并创建任务：PDF 调用 /openapi/v1/pdf/tasks，DOCX、PPTX、XLSX 调用 /openapi/v1/office/tasks。
4. 保存 data.id：创建成功返回 HTTP 202。当前公开字段是 data.id，不是 task_id。
5. 轮询任务：每 2 至 5 秒查询一次状态，直到变为 SUCCESS 或 FAILED。
6. 下载并归档：任务成功后下载译文结果，并把业务单号、任务 ID、结果路径和扣费信息写入自己的记录。

完整请求、响应字段和错误码可以直接查看文档翻译 API 5 分钟 Quickstart。

Python 示例：上传 PDF、轮询并下载结果

下面示例使用 requests。API Key 从环境变量读取，避免出现在代码仓库和截图中。

import os
import time
import uuid
from pathlib import Path

import requests

BASE_URL = "https://www.fanyipaiban.com/translate/openapi/v1"
API_KEY = os.environ["FYPB_API_KEY"]
AUTH_HEADERS = {"Authorization": f"Bearer {API_KEY}"}

source_file = Path("manual.pdf")
create_headers = {
    **AUTH_HEADERS,
    "Idempotency-Key": str(uuid.uuid4()),
}

with source_file.open("rb") as file_handle:
    response = requests.post(
        f"{BASE_URL}/pdf/tasks",
        headers=create_headers,
        files={"file": (source_file.name, file_handle, "application/pdf")},
        data={"source_lang": "auto", "target_lang": "cn"},
        timeout=120,
    )

response.raise_for_status()
task_id = response.json()["data"]["id"]

while True:
    task_response = requests.get(
        f"{BASE_URL}/tasks/{task_id}",
        headers=AUTH_HEADERS,
        timeout=30,
    )
    task_response.raise_for_status()
    task = task_response.json()["data"]

    if task["status"] == "SUCCESS":
        break
    if task["status"] == "FAILED":
        raise RuntimeError(f"Document translation failed: {task}")

    time.sleep(3)

result = requests.get(
    f"{BASE_URL}/tasks/{task_id}/download",
    headers=AUTH_HEADERS,
    timeout=120,
)
result.raise_for_status()
Path("translated-result.pdf").write_bytes(result.content)

真实生产代码还应增加最大轮询时长、网络重试、任务状态持久化、日志脱敏和失败告警。不要让一个 Web 请求持续阻塞到文档完成，使用后台队列或任务工作进程更稳妥。

DOCX、PPTX、XLSX 如何接入？

Office 文档只需要把创建地址改为 /openapi/v1/office/tasks，后续仍使用同一组任务查询和下载接口。结果文件可继续编辑，但正式使用前应复核表格、公式、跨工作表引用、幻灯片版式、字体和数字。

• DOCX：检查标题层级、表格、页眉页脚、批注和长段落。
• PPTX：检查文本框溢出、换行、字体替换和图表说明。
• XLSX：检查工作表、公式、跨表引用、数字格式和隐藏区域。
• 扫描 PDF：先用包含表格、图片、页眉页脚的代表性文件试跑，再决定是否批量提交。

批量任务最容易忽略的 4 个问题

1. 把网络超时误当成创建失败

上传超时不等于服务端没有创建任务。结果未知时应复用原 Idempotency-Key，避免重复任务和重复预占 credits；只有接口明确返回任务创建前失败后，才修复原因并使用新键。

2. 没有保存任务 ID

创建成功后立即把 data.id 与自己的业务单号绑定。轮询、下载和故障排查都依赖这个 ID。

3. 在前端暴露 API Key

API Key 应保存在服务端环境变量或密钥管理服务。不要写进网页 JavaScript、移动端包、公开仓库或可分享的截图。

4. 未经抽样就直接批量

复杂扫描件、公式、表格、示意图和密集版式会影响最终复核工作。先选择一份真正有代表性的文件完成全流程，再自动化已经确认的场景。

REST API 与 MCP 怎么选？

需要在 Codex 中使用时，可以继续阅读Codex MCP 文档翻译接入指南。REST API、MCP 与网页工作台共用同一个账户和 credits 余额。

上线前的最小验收清单

1. 使用专用 API Key 跑通一份真实代表性文档。
2. 确认能够保存 data.id，并处理 SUCCESS、FAILED 和超时。
3. 模拟创建请求超时，验证幂等键不会产生重复业务任务。
4. 下载结果并检查文件类型、内容、表格、公式、字体和版式。
5. 记录 requestId、任务 ID、业务单号和扣费字段，日志中不保存 API Key。
6. 确认失败告警、最大轮询时长和人工复核责任。

开始接入前，先从开发者专区确认能力与计费，再按公开 Quickstart跑通第一份任务。不要一开始就追求大批量，先验证一个可重复的真实场景。