API 示例

版本

API

路由

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

参数

参数	必填	类型	说明
`image`	是	file[]	一张或多张图片，或一个 ZIP 压缩包
`source_language`	否	string	可选；选择 manga 模型时必填（例如 ja）
`target_language`	是	string	目标语言代码（例如 en）
`model`	否	string	模型；省略时使用 API 默认值
`font`	否	string	字体；同时兼容旧参数 font_style

参数	必填	类型	说明
`Idempotency-Key`	是	HTTP header	准备请求头：用于在 8 小时内安全重试同一文件清单的稳定键
`platform`	否	string \| null	准备和最终提交请求：可选的调用方自报平台标签，仅用于 API 调用审计
`files[]`	是	array<object>	准备请求：包含 filename、content_type、size 和 content_sha256 的文件元数据
`upload_id`	是	string	最终提交请求：准备接口返回的不透明上传批次标识
`files[].index files[].upload_intent`	是	integer string	最终提交请求：准备接口返回的逐文件 index 和不透明 upload_intent；每个文件完成 R2 上传后再发送
`source_language`	否	string	可选；选择 manga 模型时必填（例如 ja）
`target_language`	是	string	目标语言代码（例如 en）
`model`	否	string	模型；省略时使用 API 默认值
`font`	否	string	字体；同时兼容旧参数 font_style

参数	必填	类型	说明
`batch_id`	是	string	用于查询任务状态的批次标识

参数	必填	类型	说明
无需参数

响应参数

字段	类型	说明
`task_id`	string	任务标识
`batch_id`	string	用于查询任务状态的批次标识

字段	类型	说明
`status`	integer	应用状态码；成功时为 200
`cost_ms`	integer	本次 API 请求的处理耗时（毫秒）
`request_id`	string	用于追踪本次 API 调用的请求标识
`data`	object	请求被接受后返回的翻译任务标识
`message`	string	成功的 API 响应固定为 success；不表示翻译任务已经完成
`data.task_id`	string	任务标识
`data.batch_id`	string	用于查询任务状态的批次标识

字段	类型	说明
`status_code`	integer	成功的任务状态响应固定返回 200
`request_id`	string	用于追踪本次 API 调用的请求标识
`auth_type`	string	通过 PAT 认证的任务状态请求固定为 account
`task_reference`	string	请求路径中的 batch_id，原样返回
`data`	object	逐图结果和任务整体状态的容器
`data.items`	array<object>	每张图片的任务结果数组
`data.items[].image_id`	string	图片结果的稳定标识
`data.items[].index`	integer	图片在批次中的从零开始的位置
`data.items[].filename`	string	原始图片文件名
`data.items[].status`	string	图片结果状态（pending \| processing \| completed \| failed \| canceled）
`data.items[].original_url`	string	源图片 URL；当前通过 API 创建的任务都会提供该字段。
`data.items[].translated_url`	string	译图 URL；在译图可用前为空字符串，包括图片处于等待、处理中或失败状态时。
`data.items[].is_translated`	boolean	仅当任务完成且译图 URL 可用时为 true
`data.items[].output_file_path`	string	translated_url 的兼容别名；没有可用译图时为空字符串。
`data.items[].message`	string \| null	可选信息
`data.items[].error`	string \| null	图片任务失败时的错误详情；其他情况为 null
`data.items[].inpaint_image_url`	string \| null	擦字图 URL；所选模型或执行链不生成擦字图时为 null。
`data.items[].block_json`	array<object>	V1 保留的结构化文字块；所选模型或执行链不返回文字块元数据时可能为空数组。
`data.task_status`	string	任务整体状态（pending \| processing \| completed \| failed \| canceled）

字段	类型	说明
`status`	integer	应用状态码；成功时为 200
`cost_ms`	integer	任务耗时（毫秒）；缺少有效任务时间戳时为 0
`request_id`	string	用于追踪本次 API 调用的请求标识
`data`	array<object>	精简的逐图结果数组
`message`	string	成功的 API 响应固定为 success；不表示翻译任务已经完成
`data[].image_id`	string	图片结果的稳定标识
`data[].filename`	string	原始图片文件名
`data[].status`	string	图片结果状态（pending \| processing \| completed \| failed \| canceled）
`data[].original_url`	string	源图片 URL；当前通过 API 创建的任务都会提供该字段。
`data[].translated_url`	string	译图 URL；在译图可用前为空字符串，包括图片处于等待、处理中或失败状态时。
`data[].erased_url`	string	擦字图 URL，可能为空字符串。仅返回成品译图的模型或执行链不会生成该字段，例如 Manga + Auto 成品图链路。
`data[].blocks`	array<object>	结构化翻译文字块；所选模型或执行链不返回文字块元数据时可能为空数组，例如 Manga + Auto 成品图链路。
`data[].blocks[].angle`	number	文本块的旋转角度
`data[].blocks[].color`	string	翻译文本使用的十六进制颜色
`data[].blocks[].handwritten`	boolean	源文本是否被识别为手写内容
`data[].blocks[].location`	object	文本块的四角边界
`data[].blocks[].location.left_bottom`	array<number>	对应角点的坐标对
`data[].blocks[].location.right_bottom`	array<number>	对应角点的坐标对
`data[].blocks[].location.left_top`	array<number>	对应角点的坐标对
`data[].blocks[].location.right_top`	array<number>	对应角点的坐标对
`data[].blocks[].text`	string	该文本块渲染的译文
`data[].blocks[].direction`	string	翻译文本的书写方向

字段	类型	说明
`subscription_credits`	integer	对应类别的积分余额
`subscription_credits_expires_at`	string \| null	订阅积分到期时间（ISO 8601 格式），无到期时间时为 null
`one_time_credits`	integer	对应类别的积分余额
`one_time_credits_expires_at`	string \| null	一次性积分到期时间（ISO 8601 格式），无到期时间时为 null
`free_credits`	integer	对应类别的积分余额
`total_credits`	integer	所有可用积分余额的总和
`is_temporary`	boolean	该余额是否属于临时账号

字段	类型	说明
`status`	integer	应用状态码；成功时为 200
`cost_ms`	integer	本次 API 请求的处理耗时（毫秒）
`request_id`	string	用于追踪本次 API 调用的请求标识
`data`	object	当前积分余额的容器
`message`	string	成功的 API 响应固定为 success；不表示翻译任务已经完成
`data.total_credits`	integer	所有可用积分余额的总和
`data.is_temporary`	boolean	该余额是否属于临时账号
`data.detail`	object	按类别划分的可用积分明细
`data.detail.subscription`	object	对应类别的积分余额和到期时间
`data.detail.subscription.credits`	integer	对应类别的积分余额
`data.detail.subscription.expires_at`	string \| null	积分到期时间（ISO 8601 格式），无到期时间时为 null
`data.detail.one_time`	object	对应类别的积分余额和到期时间
`data.detail.one_time.credits`	integer	对应类别的积分余额
`data.detail.one_time.expires_at`	string \| null	积分到期时间（ISO 8601 格式），无到期时间时为 null
`data.detail.free`	object	对应类别的积分余额和到期时间
`data.detail.free.credits`	integer	对应类别的积分余额
`data.detail.free.expires_at`	null	固定为 null，因为当前聚合接口不提供免费积分的单一到期时间

响应示例（JSON）

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

响应示例（JSON）

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

响应示例（JSON）

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

响应示例（JSON）

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

响应示例（JSON）

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

响应示例（JSON）

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

错误响应参数

V2 请求失败时保留 HTTP 状态，并返回相同的五字段响应封装。

字段	类型	说明
`status`	integer	实际的 HTTP 错误状态码
`cost_ms`	integer	本次 API 请求的处理耗时（毫秒）
`request_id`	string	用于追踪本次 API 调用的请求标识
`data`	object	仅包含稳定机器可读错误码的错误数据容器
`message`	string	对外错误消息；不暴露内部诊断详情
`data.code`	string	稳定的机器可读错误码

错误响应示例（JSON）

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

示例输入

API Key

源语言

目标语言

模型

字体

API 示例

路由

参数

响应参数

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

错误响应参数

错误响应示例（JSON）

示例输入

Python3 示例

cURL 示例

Python3 示例

cURL

Python3 示例

cURL

路由

参数

响应参数

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

响应示例（JSON）

错误响应参数

错误响应示例（JSON）

示例输入

Python3 示例

cURL 示例

Python3 示例

cURL

Python3 示例

cURL

Cookie 偏好设置