> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magic666.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Wan 3.0 查询视频任务

> 使用 GET /v1/videos/{task_id} 查询 Wan 3.0 视频任务状态、结果和错误信息。

# Wan 3.0 查询视频任务

Wan 3.0 视频任务是异步执行的。创建任务后，保存响应中的 `id` 或 `task_id`，再通过 `GET /v1/videos/{task_id}` 轮询任务状态。任务完成后，可以读取 `video_url`，或者使用内容代理接口下载 MP4。

## 查询任务

```http theme={null}
GET /v1/videos/{task_id}
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://magic666.top/v1/videos/task_xxxx \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  task_id = "task_xxxx"

  response = requests.get(
      f"https://magic666.top/v1/videos/{task_id}",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      timeout=30,
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const taskId = "task_xxxx";

  const response = await fetch(`https://magic666.top/v1/videos/${taskId}`, {
    method: "GET",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  });

  console.log(await response.json());
  ```
</RequestExample>

## 下载视频内容

```http theme={null}
GET /v1/videos/{task_id}/content
```

```bash theme={null}
curl -L https://magic666.top/v1/videos/task_xxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.mp4
```

下载接口建议继续携带鉴权头。任务完成后，如果查询响应没有直接返回可访问的 `video_url`，可以使用此接口获取视频内容。

## 响应示例

<ResponseExample>
  ```json 200 - 处理中 theme={null}
  {
    "id": "task_xxxx",
    "object": "video",
    "model": "wan3.0-video",
    "status": "in_progress",
    "progress": 50,
    "created_at": 1782690295,
    "video_url": null,
    "error": null
  }
  ```

  ```json 200 - 已完成 theme={null}
  {
    "id": "task_xxxx",
    "object": "video",
    "model": "wan3.0-video",
    "status": "completed",
    "progress": 100,
    "created_at": 1782690295,
    "completed_at": 1782690494,
    "video_url": "https://example.com/output.mp4",
    "metadata": {
      "content_url": "https://magic666.top/v1/videos/task_xxxx/content"
    },
    "error": null
  }
  ```

  ```json 200 - 百炼上游原始完成响应 theme={null}
  {
    "output": {
      "task_id": "fb40ef13-19e2-4418-9639-5bc89d49b33d",
      "task_status": "SUCCEEDED",
      "video_url": "https://example.com/output.mp4"
    },
    "usage": {
      "duration": 5.0,
      "output_video_duration": 5.0,
      "fps": 30,
      "ratio": "16:9"
    }
  }
  ```

  ```json 200 - 失败 theme={null}
  {
    "id": "task_xxxx",
    "object": "video",
    "model": "wan3.0-video",
    "status": "failed",
    "error": {
      "code": "generation_failed",
      "message": "video generation failed"
    }
  }
  ```
</ResponseExample>

## Path Parameters

<ParamField path="task_id" type="string" required>
  创建接口返回的任务 ID。通常使用响应中的 `id`，部分响应也会返回兼容字段 `task_id`。
</ParamField>

## 状态处理

| 状态            | 含义    | 客户端处理                             |
| ------------- | ----- | --------------------------------- |
| `queued`      | 任务排队中 | 继续轮询                              |
| `in_progress` | 视频生成中 | 继续轮询                              |
| `completed`   | 生成完成  | 读取 `video_url` 或下载 `/content`     |
| `failed`      | 生成失败  | 读取 `error.code` 和 `error.message` |

如果响应使用百炼原始结构，则：

* `output.task_status = SUCCEEDED` 表示生成成功。
* `output.task_status` 处于排队或运行状态时，继续轮询。
* 其他失败状态应按失败任务处理，并记录完整的 `output` 或错误信息。

建议轮询间隔保持在 `5` 到 `10` 秒。任务处理中不要重复提交相同的生成请求。

## Response

<ResponseField name="id" type="string">
  视频任务 ID。后续用于查询状态或下载视频内容。
</ResponseField>

<ResponseField name="task_id" type="string">
  视频任务 ID 的兼容字段，通常与 `id` 相同。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型，通常为 `video`。
</ResponseField>

<ResponseField name="model" type="string">
  任务实际使用的模型，例如 `wan3.0-video` 或 `wan3.0-video-prime`。
</ResponseField>

<ResponseField name="status" type="string">
  统一任务状态，常见值为 `queued`、`in_progress`、`completed` 和 `failed`。
</ResponseField>

<ResponseField name="progress" type="integer">
  任务进度百分比。部分上游不会稳定更新进度，客户端应以终态状态为准。
</ResponseField>

<ResponseField name="video_url" type="string">
  生成完成后的视频地址。为空或不可访问时，可使用 `/v1/videos/{task_id}/content` 下载。
</ResponseField>

<ResponseField name="metadata" type="object">
  任务附加信息，可能包含 `content_url`、过期时间或计费用量等字段。
</ResponseField>

<ResponseField name="error" type="object">
  任务失败时返回的错误对象，通常包含 `code` 和 `message`。
</ResponseField>

## 常见问题

| 现象            | 处理                                                 |
| ------------- | -------------------------------------------------- |
| 查询不到任务        | 确认使用的是创建响应返回的 `id` 或 `task_id`，并且请求使用同一个 API Token |
| 任务持续处理中       | 按 `5` 到 `10` 秒间隔继续轮询，不要重复提交                        |
| 任务完成但没有直链     | 请求 `GET /v1/videos/{task_id}/content` 下载           |
| 百炼返回 400 互斥错误 | 检查是否混传了首尾帧和参考素材                                    |
| 结果比例或清晰度不符合预期 | 创建任务时显式传 `size` 和 `aspect_ratio`                   |

## 相关接口

* [Wan 3.0 视频概览](./overview)
* [Wan 3.0 视频生成](./generation)
* [视频模型支持矩阵](/api-reference/videos/model-matrix)