API 範例

版本

API

開始使用 API

建立 API Key

登入後在控制台建立金鑰，並確認帳戶有可用點數。
上傳並提交

V2：取得上傳網址、上傳檔案，再提交翻譯任務。
查詢任務狀態

使用回傳的 batch_id 查詢進度，直到圖片處理結束。
下載譯圖

使用成功圖片回傳的譯圖連結下載結果。

示例输入

API Key

來源語言

目標語言

模型

字體

Python 3 · pip install requests

路由

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 小時內安全重試同一檔案清單的穩定鍵
`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

建立 API Key

上傳並提交

查詢任務狀態

下載譯圖

示例输入

路由

参数

回應參數

回應範例（JSON）

回應範例（JSON）

回應範例（JSON）

回應範例（JSON）

回應範例（JSON）

回應範例（JSON）

錯誤回應參數

錯誤回應範例（JSON）

Cookie 偏好設定