任務查詢與取件

建單回應的注意事項

POST /api/tasks/video-generation、POST /api/tasks/image-generation 目前回傳的欄位集合比本頁描述的查詢端點更多(包含一些尚未定案為穩定對外契約的欄位)。請只依賴本頁列出的欄位;其餘欄位可能在未來版本調整或移除,不保證穩定。

任務物件欄位(查詢端點的穩定契約)

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

欄位	說明
`public_id`	任務識別碼(ULID),所有查詢/下載都用這個值,不是可被猜測的流水號
`type`	任務類型:`1`(影片生成)/ `2`(圖片生成)
`status`	任務狀態,見下表
`credits`	這筆任務實際扣款的積分數
`params`	建單時送入的參數(含系統補上的預設值,如影片生成的 `audio`)
`result`	完成後的結果,值為 `{ 邏輯名稱: storage key }`(如 `{ "video": "results/xxx.mp4" }`);未完成為 `null`;若已超過保留期(見下方)則陣列內每個值會被置換成 `null`
`error_code` / `error_message`	失敗時的錯誤代碼/訊息,未失敗為 `null`
`created_at` / `finished_at`	ISO 8601 時間戳,`finished_at` 未結束為 `null`
`files_expire_at`	結果檔案的表面保留期限(ISO 8601),`null` 代表尚未有結果或保留機制未啟用
`files_expired`	是否已超過保留期(`true` 時 `result`/`files` 皆不再提供實際檔案位置)
`files`	`[{ key, url }]`,`key` 對應 `result` 內的鍵、`url` 是下方〈檔案下載〉端點的完整網址;過期時為空陣列
`api_key`	建立此任務所用的 Key 資訊(`{ name, key_prefix }`);對外 API(`X-Api-Key` 驗證)目前不會回傳這個欄位

`status` 各值含義

值	意義
`0`	待派工(Pending)
`5`	已排入佇列(Queued,目前系統保留、實際流程尚未使用這個中繼態)
`10`	供應商處理中(Processing)
`20`	已完成(Finished),`result`/`files` 可用
`30`	失敗(Failed),已自動退款,見〈積分與計費〉
`40`	已取消(Cancelled),已自動退款

查詢單一任務

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

publicId 必須屬於這支 Key 所在的帳號,否則回 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`	選填,日期字串	兩者任一有帶,視為查詢歷史範圍,依結束時間(`finished_at`)由新到舊排序;都不帶則回傳目前的任務,依建立時間由新到舊排序

參數不合法(如 per_page 超過 100、from 不是合法日期)回 422。

回應是標準分頁物件(Laravel paginator 格式),data 為任務物件陣列(格式同上),外層另有 current_page/last_page/per_page/total 等分頁欄位。

取消任務

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

僅排隊中(status 為 0) 的任務可以取消;一旦轉為處理中或已結束,一律回 422。
取消成功會立即退還這筆任務原本扣除的積分,回應為更新後的任務物件(status 為 40)。
publicId 不存在或不屬於這支 Key 所在的帳號,回 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://example.com/api/tasks/01K0ZC8QW3E5F1234567890ABC/files/video"
    }
  ]
}

result 的鍵名(此例為 video)= files[].key = 下載網址的 {key} 尾段,三者是同一個值;result.video 的值(results/...mp4)是內部 storage key,不是下載用的 {key}。

實務上不需要自己拼下載網址,直接取用任務物件 files 陣列裡現成的 url 呼叫即可:

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

常見錯誤:{key} 是 result 的邏輯鍵名(如 video),不是 storage 路徑(results/xxx.mp4)也不是檔名(01KX....mp4)。把 storage key 或檔名填進 {key} 會回 404。

路由與狀態碼(參考資料)

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

任務必須屬於這支 Key 所在的帳號,否則 404。
key 必須存在於該任務的 result 裡,否則 404(防止用任務 A 的授權存取任務 B 的檔案)。
已超過保留期(files_expired 為真)或物件已被物理刪除,回 410 Gone。
其餘情況以 200 串流回應檔案本身,Content-Type/Content-Length 對齊實際檔案。

狀態碼	情境
`200`	成功,回應為檔案內容本身(非 JSON)
`404`	任務不存在/不屬於你,或 `key` 不在該任務的 `result` 裡
`410`	已超過保留期,或檔案已被物理清除

錯誤總表

見〈錯誤總表〉。