[T012]DOCX翻译状态查询

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

用 JSON Body 中的 `job_id` 查询一次任务状态，立刻返回，不轮询。异步提交后由客户端反复调用本接口。第一次完成是 `ready`（响应头挂实际计费量）；之后再查同一成功任务是 `delivered`（不计费，`download_url` 仍可用）。未完成或失败的计费头为 `0.000000`。

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

请求参数

此 API 接口支持的参数列表

名称类型示例描述
job_id
必填
stringdcaf91fc699e
任务标识符，由 `POST /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 /api/v1/jobs/status`。示例：`ready`。
progress
必填
string100/100
进度字符串 `当前/100`（百分比）。`queued`/`working` 随管线更新；`ready`/`delivered` 为 `100/100`；`failed` 为 `0/100`。
direction
必填
stringzh-en
翻译方向的展示形式（`<源>-<目标>`）。当前仅实装中译英，固定为 `zh-en`。示例：`zh-en`。
download_url
必填
stringhttps://translation-gpt-docx-stage.cos.ap-beijing.myqcloud.com/results/output/20241127_dcaf91fc699e_patent.en.docx?sign=...
译文 DOCX 的对象存储签名下载地址。内部任务已是 `ready`（对外可能是 `ready` 或 `delivered`）且 COS 上传成功时才有值；未完成、`failed`、或对象存储未启用/上传失败时为空字符串 `""`。直接对该 URL 发起 GET，不经过本服务。示例：`https://...cos.../results/...?sign=...`。
source_chars
必填
integer17528
源文本字符总数（全部翻译单元的源文本长度之和）。`ready` / `delivered` 为实际值；`queued` / `working` / `failed` 为 `0`。计费头在未触发最低消费时等于 `source_chars / 1e6`；短文本会按 0.001 元保底上抬计费字符数，此时头值大于 `source_chars / 1e6`。示例：`17528`（对应计费头 `0.017528`）。
billing_amount
必填
string0.017528
按百万源字符计算的计费量，六位小数字符串，与本次响应头 `X-Openapi-Amount` 同值。同步 `ready`、以及异步第一次 `ready` 为实际用量；`delivered` / `failed` / `queued` / `working` / 异步提交为 `0.000000`。示例：`0.017528`（17528 字符）。
output_filename
stringpatent_translation.en.docx
仅内部 `output_mode=base64|both` 且 `ready` 时返回的译文字段名。示例：`patent_translation.en.docx`。
output_size_bytes
integer245760
仅内部 `output_mode=base64|both` 且 `ready` 时返回的译文字节数。示例：`245760`。
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`。

成功响应示例

成功调用 API 的响应示例

JSON 
{
  "error": "upstream translation call failed after retries",
  "job_id": "dcaf91fc699e",
  "status": true,
  "progress": "100/100",
  "direction": "zh-en",
  "error_code": 0,
  "download_url": "https://translation-gpt-docx-stage.cos.ap-beijing.myqcloud.com/results/output/20241127_dcaf91fc699e_patent.en.docx?sign=...",
  "source_chars": 17528,
  "billing_amount": "0.017528",
  "output_filename": "patent_translation.en.docx",
  "output_size_bytes": 245760,
  "file_content_base64": "UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...",
  "output_content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}

错误码

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

业务错误码

错误码描述
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