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

# MiniMax-H3 任务查询

> 使用 `GET /v1/videos/{task_id}` 查询 MiniMax-H3 视频任务状态与结果。

# MiniMax-H3 任务查询

通过任务 ID 查询视频生成或 2K 再生成任务。任务完成后，视频限时下载地址位于 `video_url` 字段。

## 方法与路径

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

<RequestExample>
  ```bash cURL theme={null}
  curl https://zx1.deepwl.net/v1/videos/task_a1b2xxxxx5f6 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  resp = requests.get(
      "https://zx1.deepwl.net/v1/videos/task_a1b2xxxxx5f6",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      timeout=30,
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://zx1.deepwl.net/v1/videos/task_a1b2xxxxx5f6",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } },
  );

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

## Path Parameters

<ParamField path="task_id" type="string" required>
  创建接口返回的任务 `id`。
</ParamField>

## 状态流转

| `status`      | 含义     | 典型 `progress` |
| ------------- | ------ | ------------- |
| `queued`      | 排队中    | 10            |
| `in_progress` | 生成中    | 50            |
| `completed`   | 成功     | 100           |
| `failed`      | 失败或已取消 | 100           |

<Note>
  建议每 5～10 秒轮询一次。上游仅保留最近 7 天的任务记录；视频下载链接有时效，请及时下载或转存。
</Note>

## 响应示例

<ResponseExample>
  ```json 200 - 已完成 theme={null}
  {
    "id": "task_a1b2xxxxx5f6",
    "object": "video",
    "model": "MiniMax-H3",
    "status": "completed",
    "progress": 100,
    "created_at": 1785125529,
    "completed_at": 1785125946,
    "seconds": "5",
    "size": "2K",
    "video_url": "https://cdn.example.com/h3-generated-2k-output.mp4",
    "metadata": {
      "url": "https://cdn.example.com/h3-generated-2k-output.mp4",
      "ratio": "16:9"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "code": "task_not_exist",
    "message": "task_not_exist",
    "data": null
  }
  ```
</ResponseExample>

## 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">
  任务使用的模型名称。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态：`queued`、`in_progress`、`completed` 或 `failed`。
</ResponseField>

<ResponseField name="progress" type="integer">
  任务进度百分比。
</ResponseField>

<ResponseField name="created_at" type="integer">
  任务创建时间，Unix 时间戳（秒）。
</ResponseField>

<ResponseField name="completed_at" type="integer">
  任务完成时间，Unix 时间戳（秒）。
</ResponseField>

<ResponseField name="expires_at" type="integer">
  结果过期时间，Unix 时间戳（秒）。
</ResponseField>

<ResponseField name="seconds" type="string">
  产物时长（秒），字符串形式。
</ResponseField>

<ResponseField name="size" type="string">
  产物分辨率。
</ResponseField>

<ResponseField name="video_url" type="string">
  视频产物的限时下载地址。
</ResponseField>

<ResponseField name="metadata" type="object">
  扩展信息。成功时包含 `url` 与实际宽高比 `ratio`。
</ResponseField>

<ResponseField name="error" type="object">
  失败原因，包含 `code` 与 `message`。
</ResponseField>

## 错误码

| HTTP 状态码 | 说明                |
| -------- | ----------------- |
| `400`    | 任务不存在或已超出 7 天查询窗口 |
| `401`    | 鉴权失败              |
| `500`    | 服务端错误             |

## 相关接口

* [MiniMax-H3 视频概览](./overview)
* [视频生成](./generation)
* [2K 再生成](./remix)
* [查询任务（统一格式）](./unified-query)