> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/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}`
提交時返回的 MixRoute 任務 ID。
```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。[萬相說明](/docs/zh-hant/api-reference/endpoint/wan)。 |
| Sora 2 | [下載影片](/docs/zh-hant/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](/docs/zh-hant/api-reference/endpoint/seedance) | [Doubao](/docs/zh-hant/api-reference/endpoint/doubao) | [Dreamina](/docs/zh-hant/api-reference/endpoint/dreamina) | [Veo](/docs/zh-hant/api-reference/endpoint/veo) | [MiniMax H3](/docs/zh-hant/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.