---
title: 查詢影片任務
description: 使用任務 ID 查詢進度、最終狀態和失敗原因。
icon: clock-3
openapi: GET /v1/videos/{task_id}
---

使用建立介面返回的任務 ID 查詢影片生成狀態。

<ParamField path="task_id" type="string" required>
  建立影片任務時返回的 `id`。
</ParamField>

## 請求示例

```bash
curl https://api.heizhu.lol/v1/videos/task_xxxxxxxxxx \
  -H "Authorization: Bearer $BLACKPIG_API_KEY"
```

## 響應欄位

<ResponseField name="id" type="string" required>
  平臺任務 ID。
</ResponseField>

<ResponseField name="object" type="string" required>
  物件型別，固定為 `video`。
</ResponseField>

<ResponseField name="model" type="string" required>
  任務使用的模型名稱。
</ResponseField>

<ResponseField name="status" type="string" required>
  `queued`、`in_progress`、`completed`、`failed` 或 `unknown`。
</ResponseField>

<ResponseField name="progress" type="integer" required>
  任務進度百分比。
</ResponseField>

<ResponseField name="created_at" type="integer" required>
  建立時間的 Unix 時間戳。
</ResponseField>

<ResponseField name="completed_at" type="integer">
  任務結束時間的 Unix 時間戳。任務尚未結束時可能不存在。
</ResponseField>

<ResponseField name="error" type="object">
  失敗錯誤物件，僅在任務失敗時返回。

  <Expandable title="error 欄位">
    <ResponseField name="code" type="string">
      穩定的錯誤型別，例如 `video_generation_failed`。
    </ResponseField>
    <ResponseField name="message" type="string">
      可供排查的失敗原因。
    </ResponseField>
  </Expandable>
</ResponseField>

## 處理中

```json
{
  "id": "task_xxxxxxxxxx",
  "object": "video",
  "model": "L-stable-seedance-2-0-933-720p",
  "status": "in_progress",
  "progress": 42,
  "created_at": 1788480000
}
```

## 已完成

```json
{
  "id": "task_xxxxxxxxxx",
  "object": "video",
  "model": "L-stable-seedance-2-0-933-720p",
  "status": "completed",
  "progress": 100,
  "created_at": 1788480000,
  "completed_at": 1788480120
}
```

## 已失敗

```json
{
  "id": "task_xxxxxxxxxx",
  "object": "video",
  "model": "L-stable-seedance-2-0-933-720p",
  "status": "failed",
  "progress": 0,
  "created_at": 1788480000,
  "completed_at": 1788480031,
  "error": {
    "code": "video_generation_failed",
    "message": "任务失败原因"
  }
}
```

<Note>
建議每 5 至 10 秒查詢一次。任務查詢的臨時網路錯誤不改變任務本身狀態。
</Note>