[T011]DOCX翻译

post
https://stage-connect.zhihuiya.com/docx-translation/api/v1/translations
在体验中心中试用

公开 REST 接口仅接受 JSON 中的 DOCX Base64，且仅支持中译英（zh→en）。翻译后始终批阅；enable_revision 只决定唯一最终 DOCX 是否显示本次修订痕迹和批注，不会跳过批阅。任务完成后，下载字段对应最终 DOCX、对照 HTML、完整 revision.json、术语溯源 JSON 四类产物；关闭溯源时为前三类。

固定外部路径；提交请求使用 JSON Body 中的 file_content_base64，仅支持 zh→en。关闭术语溯源时最多交付前三类产物。MCP 等其他接口有各自约定。

请求参数

此 API 接口支持的参数列表

名称类型示例描述
file_content_base64
必填
stringUEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...
必填。源 DOCX 字节的 Base64，不含 data: 前缀。
filename
stringpatent_translation.docx
原始 DOCX 文件名，必须以 `.docx` 结尾（1~255 字符）。未提供时默认 `document.docx`。示例：`patent_translation.docx`。
sourceLanguageCode
stringzh
源语言仅为 zh。
targetLanguageCode
stringen
目标语言仅为 en。
enable_async
boolean-
`false`（默认）：本请求内跑完并计费一次。`true`：立刻返回 `job_id`（不计费），之后用 `POST /docx-translation/api/v1/jobs/status` 查询。
user_id
stringcustomer_001
可选业务用户标识，用于加载该用户已保存的全局术语表。不会从 X-User-Id 请求头推导；省略时不加载用户全局术语表。值会去除首尾空白，不得为空或包含控制字符；长度受部署配置限制。
task_glossary
object{ "zh2en": { "处理器": "processor", "存储器": "memory" } }
可选的 zh2en 任务术语映射；任务术语优先于用户全局术语。
enable_revision
booleantrue
翻译后始终批阅。true：最终 DOCX 显示本次批阅的修订和批注；false：交付已应用有效修改的干净文档；null/省略：跟随部署展示默认值。兼容入参 auto_revision，但不能同时提交两个名称。
enable_provenance
booleantrue
是否启用术语专利溯源。省略或 null 跟随部署默认值；false 为本任务关闭；true 仅在部署已启用溯源时生效。结果通过 provenance 返回。
provenance_mode
stringstandard
可选术语溯源强度：fast、standard、full（默认）；关闭溯源时不生效。

响应结构

API 响应数据的结构说明

字段名类型示例描述
error
必填
stringupstream translation call failed after retries
`failed` 时为异常字符串；`queued` / `working` / `ready` / `delivered` 均为 `null`。示例：`null`（未失败），或 `"upstream translation call failed after retries"`（失败）。
job_id
必填
stringdcaf91fc699e
任务标识符，12 位十六进制。示例：`dcaf91fc699e`。
status
必填
stringready
任务状态：`queued` 已入队 / `working` 翻译中 / `ready` 第一次取到完成结果（计费） / `delivered` 之后再查（不计费，仍可下载） / `failed` 失败（看 `error`）。同步提交始终返回 `ready`/`failed`（内部完成后立刻标记 `billed`，不会对外改成 `delivered`）。异步提交常见 `queued`，工作线程已启动时也可能是 `working`。`delivered` 只出现在 `POST /docx-translation/api/v1/jobs/status`。示例：`ready`。
glossary
object{ "task": { "sha256": "9d5ed678fe57bcca610140957afab571f1283b3d0f7c6d8e9a0b1c2d3e4f5061", "filename": "task-glossary.json", "term_count": 2 }, "global": { "sha256": "5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e", "filename": "customer-glossary.json", "term_count": 2 }, "acceptance": { "passed": true, "report_path": "/reports/glossary-acceptance.json", "missing_terms": 0, "html_report_path": "/reports/glossary-acceptance.html", "markdown_report_path": "/reports/glossary-acceptance.md" } }
本任务使用的客户术语表摘要；未提供术语表时为 null。
job_type
stringtranslation
任务类型；本翻译提交接口为 translation。
progress
必填
string100/100
进度字符串 `当前/100`（百分比）。`queued`/`working` 随管线更新；`ready`/`delivered` 为 `100/100`；`failed` 为 `0/100`。
revision
object{ "status": "completed", "changes": 12, "summary": "Patent-quality review completed.", "warnings": [], "reviewed_units": 128, "review_complete": true, "unreviewed_units": 0, "requested_changes": 12, "failed_review_batches": 0 }
完整批阅结果对象；成功翻译任务都会执行批阅，未完成时可为 null。review_complete=false 表示有待核验项，不改变本单统一 1 倍字符计费。
direction
必填
stringzh-en
公开 REST 翻译方向为 zh-en。
provenance
object{ "summary": { "proven": 1, "term_pairs": 1, "needs_review": 0, "matched_families": 1 }, "direction": "zh2en", "term_pairs": [ { "terms": { "en": "processor", "id": 1, "zh": "处理器" }, "example": { "source": { "pn": "CN1234567A", "segment": "所述处理器执行指令。" }, "target": { "pn": "US1234567A", "segment": "The processor executes instructions." } }, "message": "Patent-family evidence found.", "origins": [ "translation" ], "segment": { "en": "The processor executes instructions.", "zh": "所述处理器执行指令。" }, "review_issue": { "code": "TERM_CONSISTENCY", "message": "Confirm terminology consistency." }, "display_status": "proven", "matched_families": { "items": [ { "source_pns": [ "CN1234567A" ], "target_pns": [ "US1234567A" ] } ], "total": 1 }, "provenance_status": "proven", "review_issue_count": 1 } ], "schema_version": "4.1", "document_version": "translated" }
术语专利溯源结果；未启用或尚未生成时为 null。
download_url
必填
stringhttps://translation-gpt-docx-stage.cos.ap-beijing.myqcloud.com/results/output/20241127_dcaf91fc699e_patent.en.docx?sign=...
唯一最终批阅后 DOCX 的签名下载链接；不会提前发布单独的未批阅译文。仅 ready/delivered 且对象存储发布成功时非空。
source_chars
必填
integer17528
源文本实际字符数；通常在 ready/delivered 可见。
auto_revision
boolean-
旧字段：仅表示本次批阅痕迹是否在最终 DOCX 中显示，不表示是否执行批阅。
billable_chars
必填
integer17528
本单计费字符数；ready/delivered 持续可见。极短文本可能因最低消费高于 source_chars。
billing_amount
必填
string0.017528
本次响应上报给 REST 网关的百万字符等价用量，不是人民币金额；首次 ready 非零，delivered/失败/处理中为 0.000000，不代表已结算订单金额为零。
output_filename
stringpatent_translation.en.docx
内部 Base64 输出模式下的同一最终批阅 DOCX 文件名；不是额外的未批阅译文产物。
progress_detail
object{ "phase": "translation", "total": 100, "current": 75, "message": "Translating document", "provenance": { "searched_terms": 12, "matched_families": 3 }, "phase_total": 4, "phase_current": 3 }
细分进度；未生成时为 null。
provenance_mode
stringstandard
溯源检索强度：fast 优先速度，standard 平衡速度和召回，full 优先召回（默认）。未启用溯源时此参数不生效。
review_executed
必填
booleantrue
当前任务是否已经执行批阅；未完成任务可能为 false。
review_required
必填
booleantrue
翻译任务必须批阅，恒为 true。
output_size_bytes
integer245760
内部 Base64 输出模式下同一最终批阅 DOCX 的字节数。
revision_json_url
必填
stringhttps://files.example.com/revision.json?sign=example
与响应中完整 revision 对象同格式的 revision.json 签名下载链接。对象存储启用时它与最终 DOCX 都是必需发布的产物，上传失败不会返回 ready；对象存储未启用或任务未完成时为空。
comparison_html_url
必填
stringhttps://files.example.com/results/patent.comparison.html?sign=...
以最终 DOCX 为准生成的对照 HTML 下载链接；发布失败或未完成时为空。
file_content_base64
stringUEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...
仅内部 `output_mode=base64|both` 且 `ready` 时返回；公开默认 `url` 模式不出现。示例：`UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...`。
output_content_type
stringapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
仅内部 `output_mode=base64|both` 且 `ready` 时返回的 MIME 类型，固定为 DOCX OOXML。示例：`application/vnd.openxmlformats-officedocument.wordprocessingml.document`。
provenance_json_url
必填
stringhttps://files.example.com/provenance.json?sign=example
最终 DOCX 的术语溯源 JSON 签名下载链接；关闭溯源或未发布时为空。
review_marks_visible
必填
booleantrue
最终 DOCX 是否显示本次批阅的修订和批注。
global_glossary_loaded
boolean-
是否已加载用户全局术语表快照。
billing_calculated_yuan
必填
string5.258400
按当前配置基础费率（默认 300 元/百万源字符）计算的订单金额，ready/delivered 均可见；这是计算值，不是网关扣款回执。
task_glossary_term_count
integer2
任务术语表词条数，未提供为 0。
comparison_html_diagnostic
object{ "upload": "succeeded", "generation": "succeeded" }
对照报告生成和上传诊断；尚无结果时为 null。可包含生成/上传状态及失败原因。
global_glossary_term_count
integer-
已加载全局术语表的词条总数，未加载为 0。
global_glossary_version_id
stringglobal-20261021-001
已加载的全局术语表版本，未加载时为 null。
global_glossary_canonical_sha256
string5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e
全局术语表规范化内容 SHA-256，未加载时为 null。

成功响应示例

成功调用 API 的响应示例

JSON 
{
  "error": "upstream translation call failed after retries",
  "job_id": "dcaf91fc699e",
  "status": true,
  "glossary": {
    "task": {
      "sha256": "9d5ed678fe57bcca610140957afab571f1283b3d0f7c6d8e9a0b1c2d3e4f5061",
      "filename": "task-glossary.json",
      "term_count": 2
    },
    "global": {
      "sha256": "5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e",
      "filename": "customer-glossary.json",
      "term_count": 2
    },
    "acceptance": {
      "passed": true,
      "report_path": "/reports/glossary-acceptance.json",
      "missing_terms": 0,
      "html_report_path": "/reports/glossary-acceptance.html",
      "markdown_report_path": "/reports/glossary-acceptance.md"
    }
  },
  "job_type": "translation",
  "progress": "100/100",
  "revision": {
    "status": "completed",
    "changes": 12,
    "summary": "Patent-quality review completed.",
    "warnings": [],
    "reviewed_units": 128,
    "review_complete": true,
    "unreviewed_units": 0,
    "requested_changes": 12,
    "failed_review_batches": 0
  },
  "direction": "zh-en",
  "error_code": 0,
  "provenance": {
    "summary": {
      "proven": 1,
      "term_pairs": 1,
      "needs_review": 0,
      "matched_families": 1
    },
    "direction": "zh2en",
    "term_pairs": [
      {
        "terms": {
          "en": "processor",
          "id": 1,
          "zh": "处理器"
        },
        "example": {
          "source": {
            "pn": "CN1234567A",
            "segment": "所述处理器执行指令。"
          },
          "target": {
            "pn": "US1234567A",
            "segment": "The processor executes instructions."
          }
        },
        "message": "Patent-family evidence found.",
        "origins": [
          "translation"
        ],
        "segment": {
          "en": "The processor executes instructions.",
          "zh": "所述处理器执行指令。"
        },
        "review_issue": {
          "code": "TERM_CONSISTENCY",
          "message": "Confirm terminology consistency."
        },
        "display_status": "proven",
        "matched_families": {
          "items": [
            {
              "source_pns": [
                "CN1234567A"
              ],
              "target_pns": [
                "US1234567A"
              ]
            }
          ],
          "total": 1
        },
        "provenance_status": "proven",
        "review_issue_count": 1
      }
    ],
    "schema_version": "4.1",
    "document_version": "translated"
  },
  "download_url": "https://translation-gpt-docx-stage.cos.ap-beijing.myqcloud.com/results/output/20241127_dcaf91fc699e_patent.en.docx?sign=...",
  "source_chars": 17528,
  "auto_revision": false,
  "billable_chars": 17528,
  "billing_amount": "0.017528",
  "output_filename": "patent_translation.en.docx",
  "progress_detail": {
    "phase": "translation",
    "total": 100,
    "current": 75,
    "message": "Translating document",
    "provenance": {
      "searched_terms": 12,
      "matched_families": 3
    },
    "phase_total": 4,
    "phase_current": 3
  },
  "provenance_mode": "standard",
  "review_executed": true,
  "review_required": true,
  "output_size_bytes": 245760,
  "revision_json_url": "https://files.example.com/revision.json?sign=example",
  "comparison_html_url": "https://files.example.com/results/patent.comparison.html?sign=...",
  "file_content_base64": "UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...",
  "output_content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "provenance_json_url": "https://files.example.com/provenance.json?sign=example",
  "review_marks_visible": true,
  "global_glossary_loaded": false,
  "billing_calculated_yuan": "5.258400",
  "task_glossary_term_count": 2,
  "comparison_html_diagnostic": {
    "upload": "succeeded",
    "generation": "succeeded"
  },
  "global_glossary_term_count": 0,
  "global_glossary_version_id": "global-20261021-001",
  "global_glossary_canonical_sha256": "5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e"
}

错误码

此接口可能返回的错误码列表

业务错误码

错误码描述
68300004请求参数异常!
68300005查询Api失败!
68300006解析基本存取错误!
68300007存在错误的请求!
68300008服务中断异常，请稍后再试!
68300010文件不符合上传规范!

平台错误码

错误码描述
67200001API整体限流错误!
67200002用户调用请求限流限制错误!
67200003申请token的key和secret不正确或者状态错误!
67200004无权限或该接口的套餐已超过系统设置的上限!
67200005账户余额不足，调用失败!
67200006客户端已过期，调用失败!
67200007超过调用额度，调用失败!

HTTP 状态码

状态码描述
0请求成功
400请求体缺失、JSON 无效、Base64 无法解码或 DOCX 容器损坏。
413Base64 解码后的源 DOCX 超过部署大小限制 API_MAX_UPLOAD_BYTES。
422参数校验失败，如缺少 file_content_base64、语言方向不符、术语表或文件名无效。
415输入不是可接受的 DOCX 内容；JSON 文件名无效通常返回 422。
503任务执行队列已满，无法接受本次提交。

性能指标

此接口的预期性能特征

正常响应时间

5000 ms

最大响应时间

10000 ms