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 偏好設定