查詢影片任務

建立任務後使用建立回應中的 id 查詢進度與結果；建立方法請見建立影片任務。

查詢狀態：GET /v1/video/generations/{task_id}

下載成品：GET /v1/videos/{task_id}/content

查詢介面會在任務完成後於 metadata.url 傳回影片位址。平台優先傳回上游的原始影片位址；只有上游沒有可用位址時，才會退回帶有 access 能力的平台成品位址。上游原始位址可能帶有簽名與到期時間，可以直接在瀏覽器或播放器中開啟；平台成品位址同樣可用。也可以攜帶 API Key 呼叫 /v1/videos/{task_id}/content 下載影片檔案。

請求參數 · path

參數	類型	必填	說明
`task_id`	string	是	建立回應中的 `id`

請求範例

curl "$LOCOPAL_API_ORIGIN/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

下載影片

任務狀態變為 completed 後，直接使用查詢回應中的 metadata.url：

curl -L "$LOCOPAL_API_ORIGIN/v1/videos/$LOCOPAL_TASK_ID/content" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -o "$LOCOPAL_TASK_ID.mp4"

回應參數

參數	類型	說明
`id`	string	公開任務 ID
`task_id`	string	與 `id` 相同的相容欄位
`object`	string	固定為 `video`
`model`	string	影片模型 ID
`status`	string	`queued`、`in_progress`、`completed`、`failed` 或 `unknown`
`progress`	integer	目前進度，範圍 0 至 100
`created_at`	integer	建立時間（Unix 秒）
`completed_at`	integer	完成時間，未完成時不傳回
`metadata.url`	string	影片位址，成功時傳回；優先為上游原始位址，必要時為平台成品位址
`metadata.upstream_created`	boolean	是否已在上游建立任務
`duration_secs`	integer	影片時長（秒），上游傳回時提供
`expires_at`	integer	上游 URL 到期時間（Unix 秒），僅在上游明確傳回時提供
`framespersecond`	integer	影片影格率，上游傳回時提供
`generate_audio`	boolean	是否生成同步音效，上游傳回時提供
`ratio`	string	輸出比例，上游傳回時提供
`resolution`	string	輸出解析度，上游傳回時提供
`seed`	integer	隨機種子，上游傳回時提供
`output_format`	string	輸出格式，例如 `mp4`，上游傳回時提供
`execution_expires_after`	integer	任務結果保留時長，上游傳回時提供
`usage`	object	任務結算後的實際用量與費用；任務尚未結算（排隊中、生成中或剛受理建立）時不傳回
`usage.prompt_tokens`	integer	本次計費的影片 token 數（與帳單「Tokens」欄左側數字一致）
`usage.completion_tokens`	integer	影片/圖片任務不單獨回報輸出 token，固定為 `0`
`usage.total_tokens`	integer	總用量，等於 `usage.prompt_tokens`
`usage.quota`	integer	本次任務實際消耗的點數
`usage.amount`	number	本次任務金額（元），由 `usage.quota` 依平台結算換算基準換算，保留 6 位小數；主控台帳單對同一筆費用會以 4 位小數顯示
`usage.currency`	string	金額幣別，固定為 `CNY`
`error.code`	string	失敗錯誤碼，僅失敗時傳回。平台影片任務終態失敗通常為 `video_generation_failed`；無法正規化的上游錯誤可能保留上游錯誤碼
`error.message`	string	失敗原因，僅失敗時傳回。平台會先剝離多層 JSON 與閘道 HTML 包裝，傳回可直接顯示的可讀文字；用戶端不要再對這段文字執行 JSON 解析

回應內容

執行中：

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1787299277
}

生成成功：

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "completed",
  "progress": 100,
  "created_at": 1787299277,
  "completed_at": 1787299581,
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800,
  "metadata": {
    "url": "https://upstream.example.com/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO.mp4?signature=...",
    "upstream_created": true
  },
  "usage": {
    "prompt_tokens": 141034,
    "completion_tokens": 0,
    "total_tokens": 141034,
    "quota": 2789652,
    "amount": 5.579304,
    "currency": "CNY"
  }
}

usage 只在任務完成結算後傳回，數值與帳單中這筆任務的扣費完全一致：usage.quota 是本次消耗的點數，usage.amount 是同一筆點數依目前站點匯率折算的人民幣金額，usage.total_tokens 是本次計費的影片 token 數。任務仍在排隊或生成中時不會傳回 usage，此時不要依查詢回應判斷費用；需要核對扣費時，請以同一個 id 在主控台帳單中比對 usage.quota 與 usage.amount。

metadata.url 可能是帶有簽名的上游位址，也可能由平台成品介面提供備援。請視同憑證處理，不要公開分享。成品生成後，建議在 expires_at 之前下載或轉存到你自己的物件儲存空間。

影片成品與預覽

除了直接讀取 metadata.url 外，也可以查詢平台成品清單：

curl "$LOCOPAL_API_ORIGIN/v1/tasks/$LOCOPAL_TASK_ID/artifacts" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

任務完成後會傳回：

{
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://locopalai.com/v1/tasks/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO/artifacts/video/content?access=..."
    }
  ]
}

成品內容位址支援 Range 請求；播放器、瀏覽器預覽與續傳下載都可以直接使用。若用戶端只讀取 metadata.url，則繼續使用原有邏輯，不需要改為成品介面。

生成失敗：

{
  "id": "task_NlersigX6rIqiOjCwTFlgNmGMTwqt39K",
  "object": "video",
  "model": "doubao-seedance-2.0-D",
  "status": "failed",
  "progress": 100,
  "created_at": 1789971935,
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  },
  "metadata": {
    "submission_stage": "submitting",
    "upstream_created": false
  }
}

error.message 是平台整理後的最終失敗文案。歷史任務即使最初儲存的是巢狀 JSON，查詢時也會傳回正規化後的文字；呼叫方直接向使用者顯示該欄位即可，不要在用戶端再拼接或解析原始的上游 JSON。

錯誤回應

查詢不存在的任務 ID（或不屬於目前帳號的任務）會傳回 HTTP 400：

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

HTTP	回應	處理
`400`	`{"code":"task_not_exist","message":"task_not_exist","data":null}`	核對任務 ID 與建立任務時的帳號
`401`	`Invalid token`	API Key 缺少、錯誤或已失效
`500`	任務查詢失敗	儲存請求 ID，稍後繼續查詢原任務

狀態處理

狀態	用戶端處理
`queued`	任務已進入佇列，請繼續查詢同一個任務 ID
`in_progress`	正在生成，請更新進度與等待時間，不要建立新任務
`completed`	讀取 `metadata.url`，或呼叫 `/v1/videos/{task_id}/content` 下載成品；建議盡快轉存
`failed`	顯示一次 `error.code` 與 `error.message`，由使用者決定是否重新提交
`unknown`	暫時無法判斷狀態，請保留任務 ID 後稍後查詢

用戶端不要以固定的等待秒數判斷是否完成，也不要因為一次網路逾時就重複建立任務；建議每 5～15 秒查詢一次。

參考素材讀取失敗

當錯誤指向 content[n].image_url、video_url，或包含 resource download failed 時，請先依陣列索引定位具體元素，再檢查：

URL 是否能從公開網路直接 GET 並傳回 200；
是否會跳轉到登入頁面，或依賴 Cookie、Referer、IP 白名單；
Content-Type 是否與檔案的真實格式一致；
臨時簽名 URL 在下載與處理期間是否仍然有效；
asset:// 素材是否屬於目前帳戶且狀態為 Active；
目前模型是否支援該素材類型與數量。

修正素材後請重新建立任務。錯誤訊息只需向使用者顯示一次可讀的原因，不要將多層轉義 JSON 重複拼接顯示。

並行、重試與計費

不同的影片任務可以並行建立；
同一個建立回應必須使用同一個任務 ID 查詢；
只有在任務明確失敗且使用者主動重試時，才發起新的建立請求；
計費依模型、解析度、時長與參考影片輸入細分，以模型廣場與最終帳單為準；參數驗證失敗（400）表示請求未被受理，通常不會產生生成任務費用。

想了解什麼	前往哪一頁
多圖、參考影片、深度影片的能力邊界與常見問題	多圖與參考影片說明
從素材入庫到影片提交的完整流程	人像素材與參考影片接入流程
素材分組、素材狀態、真人授權	素材庫介面
錯誤碼速查	錯誤碼與排查

查詢影片任務

查詢影片任務

驗證方式

請求參數 · path

請求範例

下載影片

回應參數

回應內容

影片成品與預覽

錯誤回應

狀態處理

參考素材讀取失敗

並行、重試與計費

相關文件

本頁目錄