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

# 查询视频任务

> 查询视频生成任务的状态和结果

使用创建接口返回的 MixRoute 任务 ID 查询视频任务。各模型分类页共用这里的轮询流程。

`GET https://api.mixroute.ai/v1/video/generations/{task_id}`

<ParamField path="task_id" type="string" required>
  提交时返回的 MixRoute 任务 ID。
</ParamField>

```bash theme={null}
curl "https://api.mixroute.ai/v1/video/generations/TASK_ID" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY"
```

## 响应与状态

不同路由可能直接返回任务，也可能包装在 `data` 或厂商 `task` 对象中。比较状态前统一大小写；这些是不同返回结构，不是每次响应都必须同时具备的字段。

| 状态 | 取值 | 处理 |
| - | - | - |
| 等待 | `queued`, `pending`, `submitted`, `NOT_START` | 继续轮询。 |
| 运行 | `running`, `in_progress` | 继续轮询。 |
| 成功 | `succeeded`, `SUCCESS`, `completed` | 读取结果对象并获取视频。 |
| 终止失败 | `failed`, `FAILURE`, `expired`, `cancelled`, `canceled` | 停止轮询，检查 `error`/`fail_reason`。 |

## 结果位置

| 返回结构 | 视频位置 |
| - | - |
| MixRoute 包装 | `data.result_url` / `data.url` |
| 直接任务 | `url` / `result_url` |
| Seedance 原生结果 | `content.video_url` 位于任务内部（例如 `data.data.content.video_url`）。 |
| MiniMax H3 结果 | `data.result_url` 或任务封装中的 `data.data.task.content.video_url`；厂商原生响应可能使用 `task.content.url`。 |
| Veo 原生结果 | 检查返回的全部 samples/videos；Google 原生结果可能提供 URI 或编码数据，而不是单个顶层 URL。 |
| 通义万相 | SUCCESS 后读取 data.result\_url；原生 output 与 usage 在 data.data。[万相说明](/zh-hans/api-reference/endpoint/wan)。 |
| Sora 2 | [下载视频](/zh-hans/api-reference/endpoint/download-video) |

以当前路由的实际响应为准。只检查顶层 `response.status` 或 `response.url` 的客户端会漏掉包装后的成功状态与结果。

### 示例：包装后的成功响应

```json theme={null}
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "TASK_ID",
    "status": "SUCCESS",
    "result_url": "https://example.com/generated-video.mp4"
  }
}
```

## 轮询示例

下例检查 HTTP 与业务错误，处理常见包装结构，在终止状态停止，并设置客户端超时。函数返回任务对象，由调用方处理该路由的输出字段。

```python theme={null}
import os
import time
from urllib.parse import quote
import requests

def unpack_task(payload):
    task = payload
    for _ in range(6):
        if not isinstance(task, dict):
            raise ValueError("Unexpected task response")
        if task.get("error"):
            raise RuntimeError(task["error"])
        code = task.get("code")
        if code not in (None, 0, 200, "0", "200", "success"):
            raise RuntimeError(task.get("message") or task)
        if task.get("status"):
            return str(task["status"]).lower(), task
        nested = task.get("task")
        if not isinstance(nested, dict):
            nested = task.get("data")
        if not isinstance(nested, dict):
            break
        task = nested
    raise ValueError("Task status is missing from the response")

def wait_for_video(task_id, timeout_seconds=1200):
    deadline = time.monotonic() + timeout_seconds
    url = "https://api.mixroute.ai/v1/video/generations/" + quote(task_id, safe="")
    delay = 10
    pending = {"queued", "pending", "submitted", "not_start", "running", "in_progress"}
    terminal = {"failed", "failure", "expired", "cancelled", "canceled"}
    with requests.Session() as session:
        session.headers["Authorization"] = "Bearer " + os.environ["MIXROUTE_API_KEY"]
        while time.monotonic() < deadline:
            remaining = deadline - time.monotonic()
            if remaining <= 0:
                break
            response = session.get(url, timeout=min(30, remaining))
            if response.status_code in (429, 500, 502, 503, 504):
                delay = min(delay * 2, 30)
            else:
                response.raise_for_status()
                status, task = unpack_task(response.json())
                if status in {"success", "succeeded", "completed"}:
                    return task
                if status in terminal:
                    raise RuntimeError(task.get("fail_reason") or task.get("error") or task)
                if status not in pending:
                    raise ValueError("Unknown task status: " + status)
                delay = 10
            remaining = deadline - time.monotonic()
            if remaining <= 0:
                break
            time.sleep(min(delay, remaining))
    raise TimeoutError("Video task did not finish before the client deadline")

if __name__ == "__main__":
    print(wait_for_video("TASK_ID"))
```

建议约每 10 秒查询一次，限流或临时服务错误时退避。任务成功后及时下载产物。

[Seedance](/zh-hans/api-reference/endpoint/seedance) | [Doubao](/zh-hans/api-reference/endpoint/doubao) | [Dreamina](/zh-hans/api-reference/endpoint/dreamina) | [Veo](/zh-hans/api-reference/endpoint/veo) | [MiniMax H3](/zh-hans/api-reference/endpoint/minimax-h3)

万相建议每 15 秒轮询一次。失败任务的 result\_url 可能包含失败原因，必须先确认 status 为 SUCCESS，再将其作为下载地址。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.