[T012]DOCX翻译状态查询
按 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 接口支持的参数列表
| 名称 | 类型 | 示例 | 描述 |
|---|---|---|---|
必填 | string | dcaf91fc699e | 任务标识符,由 `POST /docx-translation/api/v1/translations` 返回,长度 1~64。实际生成值为 12 位十六进制。示例:`dcaf91fc699e`。 |
响应结构
API 响应数据的结构说明
| 字段名 | 类型 | 示例 | 描述 |
|---|---|---|---|
error必填 | string | upstream translation call failed after retries | `failed` 时为异常字符串;`queued` / `working` / `ready` / `delivered` 均为 `null`。示例:`null`(未失败),或 `"upstream translation call failed after retries"`(失败)。 |
job_id必填 | string | dcaf91fc699e | 任务标识符,12 位十六进制。示例:`dcaf91fc699e`。 |
status必填 | string | ready | 任务状态:`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 | string | translation | 任务类型;本翻译提交接口为 translation。 |
progress必填 | string | 100/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必填 | string | zh-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必填 | string | https://translation-gpt-docx-stage.cos.ap-beijing.myqcloud.com/results/output/20241127_dcaf91fc699e_patent.en.docx?sign=... | 唯一最终批阅后 DOCX 的签名下载链接;不会提前发布单独的未批阅译文。仅 ready/delivered 且对象存储发布成功时非空。 |
source_chars必填 | integer | 17528 | 源文本实际字符数;通常在 ready/delivered 可见。 |
auto_revision | boolean | - | 旧字段:仅表示本次批阅痕迹是否在最终 DOCX 中显示,不表示是否执行批阅。 |
billable_chars必填 | integer | 17528 | 本单计费字符数;ready/delivered 持续可见。极短文本可能因最低消费高于 source_chars。 |
billing_amount必填 | string | 0.017528 | 本次响应上报给 REST 网关的百万字符等价用量,不是人民币金额;首次 ready 非零,delivered/失败/处理中为 0.000000,不代表已结算订单金额为零。 |
output_filename | string | patent_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 | string | standard | 溯源检索强度:fast 优先速度,standard 平衡速度和召回,full 优先召回(默认)。未启用溯源时此参数不生效。 |
review_executed必填 | boolean | true | 当前任务是否已经执行批阅;未完成任务可能为 false。 |
review_required必填 | boolean | true | 翻译任务必须批阅,恒为 true。 |
output_size_bytes | integer | 245760 | 内部 Base64 输出模式下同一最终批阅 DOCX 的字节数。 |
revision_json_url必填 | string | https://files.example.com/revision.json?sign=example | 与响应中完整 revision 对象同格式的 revision.json 签名下载链接。对象存储启用时它与最终 DOCX 都是必需发布的产物,上传失败不会返回 ready;对象存储未启用或任务未完成时为空。 |
comparison_html_url必填 | string | https://files.example.com/results/patent.comparison.html?sign=... | 以最终 DOCX 为准生成的对照 HTML 下载链接;发布失败或未完成时为空。 |
file_content_base64 | string | UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL... | 仅内部 `output_mode=base64|both` 且 `ready` 时返回;公开默认 `url` 模式不出现。示例:`UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...`。 |
output_content_type | string | application/vnd.openxmlformats-officedocument.wordprocessingml.document | 仅内部 `output_mode=base64|both` 且 `ready` 时返回的 MIME 类型,固定为 DOCX OOXML。示例:`application/vnd.openxmlformats-officedocument.wordprocessingml.document`。 |
provenance_json_url必填 | string | https://files.example.com/provenance.json?sign=example | 最终 DOCX 的术语溯源 JSON 签名下载链接;关闭溯源或未发布时为空。 |
review_marks_visible必填 | boolean | true | 最终 DOCX 是否显示本次批阅的修订和批注。 |
global_glossary_loaded | boolean | - | 是否已加载用户全局术语表快照。 |
billing_calculated_yuan必填 | string | 5.258400 | 按当前配置基础费率(默认 300 元/百万源字符)计算的订单金额,ready/delivered 均可见;这是计算值,不是网关扣款回执。 |
task_glossary_term_count | integer | 2 | 任务术语表词条数,未提供为 0。 |
comparison_html_diagnostic | object | {
"upload": "succeeded",
"generation": "succeeded"
} | 对照报告生成和上传诊断;尚无结果时为 null。可包含生成/上传状态及失败原因。 |
global_glossary_term_count | integer | - | 已加载全局术语表的词条总数,未加载为 0。 |
global_glossary_version_id | string | global-20261021-001 | 已加载的全局术语表版本,未加载时为 null。 |
global_glossary_canonical_sha256 | string | 5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e | 全局术语表规范化内容 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 | 文件不符合上传规范! |
平台错误码
| 错误码 | 描述 |
|---|---|
67200001 | API整体限流错误! |
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