文档翻译 API | Document-Translator.com

快速入门

登录并创建 API 密钥. 将其中的 .env 条目复制到示例文件旁边的私有 .env 文件中。API 翻译会使用账户额度，包括符合条件的注册赠送额度；网站每日限额不适用。切勿提交密钥，或将其放入公开的浏览器代码中。
下载 Node.js 示例. 请使用 Node.js 22 或更高版本；无需安装任何软件包。将一份简短的 UTF-8 文本文档保存为同一文件夹中的 input.txt。此示例最多支持 16,000 个字符；更大的文档可通过下方 API 使用多个片段。
运行第一条命令，在不使用额度的情况下查看报价。查看后，运行第二条命令，翻译为西班牙语并保存为 translated.txt。请按需替换语言和路径。

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

示例会持续轮询直至任务就绪，且不会覆盖现有输出。保留其 .translation.json 检查点；若中断，请重新运行同一命令：它会恢复现有任务并下载结果，不会再次扣费。检查点不包含文档文本或 API 密钥。等待超时不会取消处理。

翻译API接收提取的文字并返回翻译后的片段。可选的私密备份支持在完成后24小时内恢复文档。请在客户端重建最终文档。

或者复制 https://document-translator.com/developers/ 并交给你的 AI 智能体，让它帮助你开始使用。

构建文档翻译工作流

在应用中提取文本并为各片段分配稳定的 ID。发送下方所示的负载，然后使用返回的各个 ID 将译文放回文档中。

创建报价

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

响应中包含报价 ID、源文字数、准确点数费用和有效期。报价有效期为十分钟。请求报价不会预留点数或保存文档文本。

报价默认要求严格输出。要允许部分结果，请在报价URL中添加output=best-effort-v1。就绪结果包含outcome和issues，使用前请检查。这项策略在报价时固定。

POST /api/v1/quotes?output=best-effort-v1

开始翻译

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

开始时再次发送原始报价负载。服务器会在存储文本或预留额度前验证其所有者和规范哈希。JSON 对象键的顺序无关紧要；如果更改文本、片段顺序、格式、指纹或语言，则需要重新报价。

读取翻译结果

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

使用片段 ID 重建文件；结果端点返回的是 JSON，而不是完整文档。请在客户端保留空白、链接、样式和其他不可翻译的结构。每个片段都需要一个长度为 1–48 个字符的唯一 ID，只能使用 a–z、0–9、下划线或连字符。片段文本最多可包含 16,000 个 UTF-16 代码单元。指纹是原始文件字节的小写 SHA-256 哈希值。

网站负责解析和重建文档。API客户端需提供提取的文字并自行重建文件。浏览器OCR支持六种语言的清晰扫描件，详见首页常见问题。复杂排版可能使用续页或易读的备用格式。

使用 cURL 获取报价

将上方的报价 JSON 保存为 payload.json，并在 shell 中设置 DOCUMENT_TRANSLATOR_API_KEY。此命令仅请求报价。要开始翻译，请将包含返回的报价 ID 和相同负载的启动 JSON 发送到 translations 端点。

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

在 PowerShell 中，请使用 curl.exe 和 $env:DOCUMENT_TRANSLATOR_API_KEY；将命令写在一行中，而不是使用上方显示的反斜杠续行写法。

翻译额度和 API 密钥

每份 API 文档会在限额内预留一个账户额度。严格模式任务仅在验证通过并准备就绪后才扣费；失败或取消的未完成任务会释放预留额度。使用尽力而为输出时，少量缺漏可能仍会使用约定额度；若存在重大缺漏或关键错误，则会释放额度。请查看 outcome.creditOutcome 和 outcome.completion，不要假设每个就绪的结果都已扣费。

每个账户最多可创建五个有效 API 密钥。密钥仅显示一次，以哈希形式存储，并可在“账户”中撤销。有效密钥可访问该账户的付费翻译，包括使用同一账户下其他密钥创建的任务。密钥不能用于登录或付款。

重试与中断的请求

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

如果启动请求的结果不确定，请使用相同的报价 ID、载荷和幂等键重试。完全相同的重试请求会返回已有任务，不会再次扣费。若载荷已更改，或将同一个键用于其他报价，则会返回 409。任务和幂等性元数据会在任务终止后保留七天。

只要源文本仍可用，可重试可恢复的失败任务。重试会保留任务 ID，并复用已完成的文本块。每个任务最多可尝试处理三次。下载失败时，可重试结果接口，而无需重新开始翻译。

轮询与下载

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

批量状态查询最多接受100个 ID，并返回 { jobs: [...] }，其中仅包含已授权且未删除的任务。处理中时约每五秒轮询一次，排队中时约每十五秒轮询一次。恢复超过100个任务时，请公平轮换批次。标签页隐藏时暂停轮询；任务进入终止状态或遇到永久授权错误时停止轮询。

状态为 ready 时，请使用相同的账户授权获取结果。结果包含翻译文本段映射，可用于在本地重建文件。结果在完成后 24 小时内可访问；无效输入会在创建一小时后过期。过期结果会返回 410。已删除或无法访问的任务会返回 404。

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

使用 PUT 保存已完成的文件，并提供二进制正文、Content-Length 和匹配的 Content-Type。支持的扩展名为 docx、pdf、txt 和 md，每种格式只能保存一个文件，输出文件大小上限为 50 MB。重复执行成功的保存操作会保留现有文件。使用 GET 下载已保存的文件；任务状态中的 savedFormats 会列出可用格式。保存和下载使用相同的任务所有权检查，不额外消耗积分，也不会延长 24 小时的期限。

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

DELETE 会取消尚未完成的任务，或移除可用文本和已保存文件。删除已完成的结果不会退还额度，也不会延长下载期限。此版本不提供任务完成 Webhook。

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

账户余额与记录

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

历史记录仅限当前所有者查看，并使用返回的分页游标。余额接口使用浏览器账户会话，仅返回最基本的登录和余额信息。Checkout 处于待处理状态时，每五秒轮询一次，最多十次；页面隐藏时暂停轮询，并在到账或账户退出登录时停止。

n8n、Make 和 Zapier

使用带有机密 Bearer 凭据的 HTTP 请求步骤。先提取文本，将 JSON 负载 POST 到报价端点，然后将报价 ID、负载和一个稳定的 16–80 字符幂等键 POST 到 translations 端点。添加延迟并通过 GET 查询状态，直到任务就绪；随后获取结果并重建或保存译文。请将报价 ID 和重试键与工作流记录一并保存。无需专用连接器或 multipart 上传。

限制与错误

每份文档最多 50,000 个源文本词、400,000 个提取字符和 12,000 个文本片段。浏览器还会限制原始文件大小为 25 MB、PDF 为 300 页、PowerPoint 文件为 300 张幻灯片。这些是源文件限制，会在开始翻译前检查。
每个账户最多可有 100 份排队中或处理中的文档。API 密钥共享每分钟 120 次报价，以及每个账户每十秒 5 次新建任务或重试。收到 429 响应时，请遵循 Retry-After；临时故障时请使用有上限的退避重试。提高轮询频率不会加快处理速度。
严格输出会在扣费前拒绝缺失、重复或格式错误的译文片段。尽力而为输出会保留已验证的译文；未解决部分可能保留原文，结果和问题会在 outcome 和 issues 中说明。不会在文档内容中添加水印或服务署名。

错误信息包含错误消息和代码。400 表示输入无效，401 表示授权无效，402 表示点数不足，404 表示任务不可用，409 表示报价或状态冲突，410 表示已过期，429 表示请求频率或容量超限，503 表示服务不可用。

我们会将原始文档的私密副本保留至翻译完成后24小时，以便您恢复下载。您可以通过删除翻译提前移除副本。发送给翻译服务提供方的只有提取的文字。隐私详情