文档翻译 API | Document-Translator.com

快速入门

登录并创建 API 密钥. 请将密钥存储在服务器的机密配置中。API 翻译需要预付额度；浏览器免费额度不适用。
在您的客户端中提取文档文本，为每个片段分配稳定 ID，然后请求报价。请在本地保留原始文档，以便重建。
使用报价 ID、稳定的幂等键和相同的负载启动任务。轮询状态直至任务就绪，然后获取翻译后的片段并重建文档。

翻译 API 接收提取的文本并返回翻译后的文本段。请在客户端构建完成的文件，然后可选择保存该翻译文件以供稍后下载。请勿上传原始文件。

创建报价

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

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

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

开始翻译

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

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

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

构建文档翻译工作流

在您的应用中提取文本并重新生成下载文件。发送上方显示的负载，然后使用返回的片段 ID，将每段译文放回对应文档。

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

DOCX 会保留受支持的原始结构。PDF 导出会重新排版文本，不会还原精确的页面布局。不支持扫描版或受密码保护的 PDF。使用前请检查重要译文和格式。

翻译额度和 API 密钥

每份 API 文档在上传限制内使用 1 个账户额度。额度会在任务开始时预留，并在完整且通过验证的译文就绪后扣除。注册奖励额度可通过 API 使用；每日免费额度仅限在网站使用。

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

重试与中断的请求

如果启动请求的结果不确定，请使用相同的报价 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

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

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

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

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

账户余额与记录

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

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

限制与错误

每份文档最多支持 50,000 个源词、400,000 个提取字符和 12,000 个文本片段。浏览器还限制原始文件不得超过 25 MB，PDF 不得超过 100 页。
每个账户最多可有 100 份文档处于排队或处理中。开始翻译和重试共用速率限制。收到 429 响应时，请遵循 Retry-After 指示；遇到临时故障时，请使用有上限的退避重试。
缺失、重复或格式错误的译文片段会在发布和扣费前导致验证失败。失败或取消的未完成任务会释放预留额度。

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

原始文档保留在你的客户端。提取的文本会交由我们的翻译服务提供商处理，已保存的译文文件会私密存储，以供下载。临时存储内容会按计划清理；服务提供商的保留政策也同样适用。隐私详情