任務查詢與取件

建立任務後,可以用以下 API 查詢進度、取消任務和下載結果。

建立任務時的回應

建立影片、全能參考影片、文生影片、圖片任務時,回應裡的欄位可能比本頁列出的多。請只使用本頁列出的欄位,其他欄位之後可能會調整或移除。

任務資料欄位

GET /api/tasks 和 GET /api/tasks/{publicId} 回傳的每一筆任務都包含以下欄位:

欄位	說明
`public_id`	任務編號,查詢和下載都用這個值
`type`	任務類型:`1` 圖生影片、`2` 圖片生成、`3` 人臉年齡偵測、`4` 全能參考影片、`5` 文生影片
`status`	任務狀態,見下表
`credits`	這筆任務扣除的積分
`params`	建立任務時送出的參數,包含系統補上的預設值(例如影片的 `audio`)
`result`	任務結果,未完成時是 `null`。影片和圖片任務是 `{ 名稱: 檔案位置 }`,例如 `{ "video": "results/xxx.mp4" }`,實際檔案請用下方〈檔案下載〉取得;超過保存期限後,檔案位置會變成 `null`。人臉年齡偵測是 `{ "face_coordinates": [...] }`,不受保存期限影響,見〈人臉年齡偵測〉
`error_code` / `error_message`	失敗時的錯誤代碼和訊息,沒失敗時是 `null`
`created_at` / `finished_at`	建立時間和結束時間(ISO 8601),還沒結束時 `finished_at` 是 `null`
`files_expire_at`	結果檔案的保存期限(ISO 8601),還沒有結果時是 `null`
`files_expired`	是否已超過保存期限。`true` 時無法再下載檔案
`files`	可下載的檔案清單 `[{ key, url }]`,`url` 可以直接用來下載。超過保存期限時是空陣列;人臉年齡偵測沒有檔案,永遠是空陣列

`status` 狀態值

值	意思
`0`	排隊中
`2`	年齡檢查中。有放 `images` 的生成任務會先停在這裡,通過後變成 `0`,見〈生成前年齡檢查〉
`5`	保留值,目前不會出現
`10`	處理中
`20`	已完成,可以取得 `result` 和 `files`
`30`	失敗,積分已自動退回,見〈積分與計費〉
`40`	已取消,積分已自動退回

查詢單一任務

GET /api/tasks/{publicId}
X-Api-Key: sk-live-xxxx

publicId 必須是這把金鑰所屬帳號的任務,否則會回傳 404({ "message": "Task not found." })。
任務結束後仍然可以繼續查詢。

查詢任務列表

GET /api/tasks?per_page=20
GET /api/tasks?from=2026-07-01&to=2026-07-11&per_page=20
X-Api-Key: sk-live-xxxx

參數	說明
`per_page`	選填,每頁幾筆,`1`–`100`,預設 `20`
`from` / `to`	選填,日期。有帶其中一個時查詢歷史任務,依結束時間從新到舊排序;都不帶時回傳目前的任務,依建立時間從新到舊排序

參數有誤(例如 per_page 超過 100、from 不是有效日期)會回傳 422。

回應是分頁格式:data 是任務資料陣列,另外有 current_page、last_page、per_page、total 等分頁欄位。

取消任務

POST /api/tasks/{publicId}/cancel
X-Api-Key: sk-live-xxxx

只有排隊中(status 為 0)或年齡檢查中(status 為 2)的任務可以取消。已經開始處理或已結束的任務會回傳 422。
取消成功會立即退回這筆任務扣的積分,回應是更新後的任務資料(status 為 40)。
任務不存在或不屬於這把金鑰的帳號,會回傳 404。

檔案下載

以一筆已完成的影片任務為例,GET /api/tasks/{publicId} 的回應如下(只列出相關欄位):

{
  "public_id": "01K0ZC8QW3E5F1234567890ABC",
  "status": 20,
  "result": {
    "video": "results/01K0ZC8QW3E5F1234567890ABC.mp4"
  },
  "files_expire_at": "2026-07-20T08:00:00.000000Z",
  "files_expired": false,
  "files": [
    {
      "key": "video",
      "url": "https://yuyuvideo.com/api/tasks/01K0ZC8QW3E5F1234567890ABC/files/video"
    }
  ]
}

直接使用 files 裡的 url 下載即可,不需要自己組網址:

curl -H "X-Api-Key: sk-live-xxxx" \
  "https://yuyuvideo.com/api/tasks/01K0ZC8QW3E5F1234567890ABC/files/video" \
  -o output.mp4

注意:網址最後的 video 是 result 裡的欄位名稱,和 files[].key 相同。不要填成檔案路徑(results/xxx.mp4)或檔名,否則會回傳 404。

下載 API 說明

GET /api/tasks/{publicId}/files/{key}
X-Api-Key: sk-live-xxxx

狀態碼	情況
`200`	成功,回傳檔案本身(不是 JSON)
`404`	任務不存在、不屬於你,或 `key` 不在這筆任務的 `result` 裡
`410`	已超過保存期限,或檔案已被刪除

錯誤代碼

所有錯誤代碼請見〈錯誤總表〉。