[T012]DOCX翻译状态查询

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

按 job_id 查询状态。仅在任务 ready/delivered 后,download_url、comparison_html_url、revision_json_url、provenance_json_url 才可能提供对应产物链接;关闭溯源时 provenance_json_url 为空。首次 ready 上报本次计费用量,再次查询为 delivered、用量归零,但计费字符数和订单计算金额保留。批阅始终执行,enable_revision 只影响最终 DOCX 的痕迹展示。

固定 path,`job_id` 只放在 JSON Body。本接口不下载文件;`ready` 后直接访问 `download_url`。

请求参数

此 API 接口支持的参数列表

名称类型示例描述
job_id
必填
stringdcaf91fc699e
任务标识符,由 `POST /docx-translation/api/v1/translations` 返回,长度 1~64。实际生成值为 12 位十六进制。示例:`dcaf91fc699e`。

响应结构

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请求成功
404任务不存在
422请求体缺少 `job_id`,或 `job_id` 为空 / 超过 64 字符。本接口走 FastAPI 默认 Body 校验,`detail` 是错误对象数组,不是字符串。

性能指标

此接口的预期性能特征

正常响应时间

5000 ms

最大响应时间

10000 ms