在哪里可以找到 [T011]DOCX翻译的 OpenAPI schema？

OpenAPI schema 位于 /openapi.json#/paths/~1docx-translation~1api~1v1~1translations/post，也可在 /openapi.json 浏览完整规范。

[T011]DOCX翻译

Q: [T011]DOCX翻译 的接口地址是什么？

[T011]DOCX翻译 的接口为 POST https://stage-connect.zhihuiya.com/docx-translation/api/v1/translations。

Q: [T011]DOCX翻译 可以返回哪些数据？

[T011]DOCX翻译：提交 DOCX 翻译。别名：`POST /api/translate-document`。公开 API 支持 JSON（`file_content_base64`）或 multipart 上传（`document`/`file`）；**不支持** `file_url`（URL 提交请用 MCP 工具 `translation_docx`）。`enable_async=false`（默认）同步；`enable_async=true` 异步。。完整响应结构请参见本页的响应结构与成功响应示例。

post

https://stage-connect.zhihuiya.com/docx-translation/api/v1/translations

在体验中心中试用

提交 DOCX 翻译。别名：`POST /api/translate-document`。公开 API 支持 JSON（`file_content_base64`）或 multipart 上传（`document`/`file`）；**不支持** `file_url`（URL 提交请用 MCP 工具 `translation_docx`）。`enable_async=false`（默认）同步；`enable_async=true` 异步。

公开 API：JSON Base64 或 multipart。`file_url` 仅 MCP，见文档 `x-mcp`。

请求参数

此 API 接口支持的参数列表

名称	类型	示例	描述
`file_content_base64` 必填	`string`	`UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...`	源 DOCX 文件字节的 Base64 字符串（JSON 模式必填），不包含 `data:` URL 前缀。DOCX 为 ZIP 容器，编码后通常以 `UEsDBB`（`PK\x03\x04` 魔数）开头。体积约为原文件的 1.33 倍。示例：`UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...`。
`filename`	`string`	`patent_translation.docx`	原始 DOCX 文件名，必须以 `.docx` 结尾（1~255 字符）。未提供时默认 `document.docx`。示例：`patent_translation.docx`。
`sourceLanguageCode`	`object`	`zh`	源语言代码，默认 `zh`。DOCX 链路当前仅实装 `zh` -> `en`；其他组合返回 422 并提示 `unsupported language pair`。示例：`zh`。
`targetLanguageCode`	`object`	`en`	目标语言代码，默认 `en`。DOCX 链路当前仅实装 `zh` -> `en`；其他组合返回 422 并提示 `unsupported language pair`。示例：`en`。
`enable_async`	`boolean`	-	`false`（默认）：本请求内跑完并计费一次。`true`：立刻返回 `job_id`（不计费），之后用 `POST /api/v1/jobs/status` 查询。

{
  "filename": "patent_translation.docx",
  "enable_async": false,
  "sourceLanguageCode": "zh",
  "targetLanguageCode": "en",
  "file_content_base64": "UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL..."
}

响应结构

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 /api/v1/jobs/status`。示例：`ready`。
`progress` 必填	`string`	`100/100`	进度字符串 `当前/100`（百分比）。`queued`/`working` 随管线更新；`ready`/`delivered` 为 `100/100`；`failed` 为 `0/100`。
`direction` 必填	`string`	`zh-en`	翻译方向的展示形式（`<源>-<目标>`）。当前仅实装中译英，固定为 `zh-en`。示例：`zh-en`。
`download_url` 必填	`string`	`https://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` 必填	`integer`	`17528`	源文本字符总数（全部翻译单元的源文本长度之和）。`ready` / `delivered` 为实际值；`queued` / `working` / `failed` 为 `0`。计费头在未触发最低消费时等于 `source_chars / 1e6`；短文本会按 0.001 元保底上抬计费字符数，此时头值大于 `source_chars / 1e6`。示例：`17528`（对应计费头 `0.017528`）。
`billing_amount` 必填	`string`	`0.017528`	按百万源字符计算的计费量，六位小数字符串，与本次响应头 `X-Openapi-Amount` 同值。同步 `ready`、以及异步第一次 `ready` 为实际用量；`delivered` / `failed` / `queued` / `working` / 异步提交为 `0.000000`。示例：`0.017528`（17528 字符）。
`output_filename`	`string`	`patent_translation.en.docx`	仅内部 `output_mode=base64\|both` 且 `ready` 时返回的译文字段名。示例：`patent_translation.en.docx`。
`output_size_bytes`	`integer`	`245760`	仅内部 `output_mode=base64\|both` 且 `ready` 时返回的译文字节数。示例：`245760`。
`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`。

成功响应示例

成功调用 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`	文件不符合上传规范!

平台错误码

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

HTTP 状态码

状态码	描述
`0`	请求成功
`400`	请求体缺失、JSON 无效、Base64 无法解码、DOCX 容器损坏，或 multipart 场景下语言方向未实装（JSON 语言错误走 422）。空 Body 示例见下。
`413`	源文件超过大小限制（默认 `API_MAX_UPLOAD_BYTES` = 50 MB）。JSON Base64 文案为 `decoded DOCX exceeds API_MAX_UPLOAD_BYTES`；multipart 为 `uploaded file exceeds API_MAX_UPLOAD_BYTES`。
`422`	JSON Body 校验失败：缺少 `file_content_base64`、`filename` 不以 `.docx` 结尾，或语言校验失败（码表外、源目标相同、方向未实装）。`detail` 为 Pydantic 校验原文。
`415`	上传文件名不以 `.docx` 结尾。JSON Body 里非法 `filename` 会先被 Pydantic 拦成 422；本状态码主要出现在 multipart 上传。

性能指标

此接口的预期性能特征

正常响应时间

5000 ms

最大响应时间

10000 ms