一个任务 ID 串联完整流程
创建接口返回 HTTP 202。保存 data.id，后续轮询状态和下载结果都使用这个任务 ID。
在开发者中心创建专用 API Key，并将密钥保存到环境变量或密钥管理服务。
使用 multipart/form-data 上传 PDF 或 Office 文件，同时指定目标语言和唯一的 Idempotency-Key。
每 2 至 5 秒查询一次任务，直到状态变为 SUCCESS 或 FAILED。
任务 SUCCESS 后，继续使用同一 API Key 调用下载地址并保存结果文件。
创建并妥善保存 API Key
在开发者中心创建专用 API Key。完整密钥只在创建时展示一次。
- 将密钥保存到环境变量或密钥管理服务，不要写进前端 JavaScript 或公开仓库。
- 选择一份有代表性的测试文件。扫描件、表格、图片或复杂排版较多时，先用一小份但足够复杂的样例。
- 每次业务操作生成一个 Idempotency-Key。网络超时且结果未知时复用原键；如果接口已明确返回任务创建前失败，修复原因后使用新键。最大长度为 128 个字符。
上传 PDF 并创建任务
以 multipart/form-data 发送文件、源语言和目标语言。下面示例把 PDF 翻译为中文。
export FYPB_API_KEY="your_api_key"
curl -X POST \
'https://www.fanyipaiban.com/translate/openapi/v1/pdf/tasks' \
-H "Authorization: Bearer ${FYPB_API_KEY}" \
-H 'Idempotency-Key: quickstart-pdf-001' \
-F 'file=@./manual.pdf' \
-F 'source_lang=auto' \
-F 'target_lang=cn'从 data.id 读取任务 ID
响应外层包含 success、requestId 和 data。不要读取 task_id，当前公开字段是 data.id。
{
"success": true,
"requestId": "api-request-id",
"data": {
"id": "document-task-id",
"type": "PDF",
"billingUnit": "PER_PAGE",
"status": "QUEUED",
"progress": 0,
"billablePageCount": 12,
"pageTokenPrice": 1500,
"estimatedToken": 18000,
"chargedToken": null,
"downloadPath": "/openapi/v1/tasks/document-task-id/download",
"markdownDownloadPath": "/openapi/v1/tasks/document-task-id/download-markdown",
"comparisonDownloadPath": "/openapi/v1/tasks/document-task-id/download-comparison"
}
}轮询直到 SUCCESS 或 FAILED
建议每 2 至 5 秒查询一次。QUEUED 和 RUNNING 表示仍在处理；SUCCESS 与 FAILED 是终态。
TASK_ID="document-task-id"
curl \
"https://www.fanyipaiban.com/translate/openapi/v1/tasks/${TASK_ID}" \
-H "Authorization: Bearer ${FYPB_API_KEY}"SUCCESS 后下载结果
主下载接口返回译文 PDF 或可编辑的 Office 文件。在任务完成前调用会返回 409 RESULT_NOT_READY。
curl -L \
"https://www.fanyipaiban.com/translate/openapi/v1/tasks/${TASK_ID}/download" \
-H "Authorization: Bearer ${FYPB_API_KEY}" \
-o translated-result.pdf一个成功的 PDF 任务可提供三类结果
/tasks/{id}/download主要的翻译与排版结果。/tasks/{id}/download-markdown仅 PDF 支持，适合知识库、检索或下游处理。/tasks/{id}/download-comparison仅 PDF 支持，便于继续复核。DOCX、PPTX、XLSX 使用同一套流程
只需要替换创建任务的地址，后续仍然使用统一的任务查询和下载接口。
curl -X POST \
'https://www.fanyipaiban.com/translate/openapi/v1/office/tasks' \
-H "Authorization: Bearer ${FYPB_API_KEY}" \
-H 'Idempotency-Key: quickstart-office-001' \
-F 'file=@./product-spec.xlsx' \
-F 'source_lang=auto' \
-F 'target_lang=cn'按错误码处理重试，不要盲目重复创建
保留错误响应中的 requestId，便于将一次失败调用与 API 日志对应起来。
| HTTP | 常见错误码 | 处理方式 |
|---|---|---|
400 | MISSING_IDEMPOTENCY_KEY / INVALID_IDEMPOTENCY_KEY / MISSING_TARGET_LANGUAGE | 补齐或修正必填请求头、表单字段，再创建新请求。 |
401 | MISSING_API_KEY / INVALID_API_KEY | 检查 Authorization 请求头、Bearer 密钥是否正确，以及密钥是否仍处于启用状态。 |
402 | INSUFFICIENT_CREDITS | 充值共享余额，然后使用新的 Idempotency-Key 创建新请求。 |
409 | IDEMPOTENCY_KEY_IN_PROGRESS | 短暂等待后，使用相同 Idempotency-Key 重试同一个创建请求。 |
409 | IDEMPOTENCY_KEY_REUSED | 上一请求在创建任务前失败。修复原因后，使用新的 Idempotency-Key。 |
409 | RESULT_NOT_READY | 继续轮询现有任务，仅在状态变为 SUCCESS 后下载。 |
503 | PARSER_UNAVAILABLE | 稍后使用新的 Idempotency-Key 重试，因为上一请求已明确失败。 |
先明确什么算一个计费页
PDF 与 Office 文档翻译当前按 1,500 credits / 计费页收费，API 与网页工作台共用同一个余额。
正式接入前需要确认的问题
为什么必须使用 Idempotency-Key？
文件上传可能在服务端已经开始创建任务后发生网络超时。结果未知时复用相同幂等键，可以避免重复创建任务和重复预占 credits；如果接口已明确返回任务创建前失败，修复原因后应使用新键。
可以直接从浏览器前端调用 API 吗？
不要把 API Key 暴露在前端代码中。应由服务端、任务工作进程或受控的自动化环境保存密钥并调用文档翻译 API。
扫描 PDF 适合直接批量提交吗？
建议先测试一份代表性样例，尤其要覆盖表格、图片、页眉页脚或排版密集的页面。识别质量和版式复杂度会影响后续复核与交付流程。
API 会使用单独的 credits 余额吗？
不会。API、MCP 与网页工作台共用同一个 credits 余额，可以先在网页工作台试样，再自动化已经确认的流程。
先用一份代表性文档跑通流程
完整测试上传、轮询和下载，并检查结果与 chargedToken，再接入批量或正式生产流程。