> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # 视频生成 > 使用 AIHubMix 原生视频协议创建异步任务、查询状态并下载视频。 AIHubMix 原生视频协议使用 `/ai/v1/videos` 系列端点。视频生成固定异步，请求提交后返回 任务 ID，客户端轮询详情或接收 Webhook，完成后下载视频。 使用原生视频任务接口前，需要为当前账户开启异步任务功能。未开启时，任务创建请求返回 `403 async_not_enabled`。 ## 快速开始 下面使用 `wan2.6-t2v` 创建一个 5 秒视频。 ```bash 创建任务 theme={null} curl -X POST https://aihubmix.com/ai/v1/videos \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-t2v", "prompt": "Ocean waves crashing on rocky cliffs at sunset", "duration": 5, "size": "1280x720" }' ``` ```json 创建响应 theme={null} { "id": "task_01K0ABCDEF", "object": "video", "model": "wan2.6-t2v", "status": "in_progress", "output": [], "error": null, "created_at": 1784707200, "completed_at": null, "expires_at": null } ``` ```bash 查询任务 theme={null} curl https://aihubmix.com/ai/v1/videos/{id} \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" ``` ```bash 下载视频 theme={null} curl https://aihubmix.com/ai/v1/videos/{id}/content \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ --output result.mp4 ``` ## 接口概览 | 场景 | 方法 | 路径 | 说明 | | ------ | ---- | ---------------------------- | ---------------------- | | 创建视频 | POST | `/ai/v1/videos` | 提交固定异步的视频生成任务 | | 查询视频详情 | GET | `/ai/v1/videos/{id}` | 返回任务最新状态 | | 查询视频列表 | GET | `/ai/v1/videos` | 返回当前 API Key 创建的视频任务快照 | | 下载视频 | GET | `/ai/v1/videos/{id}/content` | 下载任务的主视频结果 | Base URL：`https://aihubmix.com` 认证方式： ```text theme={null} Authorization: Bearer $AIHUBMIX_API_KEY ``` ## 查询模型 Schema 模型目录可以筛选已经提供请求 Schema 的文生视频模型： ```bash theme={null} curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order" ``` 取得 `model_id` 后，查询该模型实际支持的端点： ```bash theme={null} curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" ``` 同一模型可能同时返回 AIHubMix 原生与 OpenAI 兼容端点。应按 `path` 选择原生视频接口， 再读取对应的 `request.schema`： ```bash theme={null} curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \ | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema' ``` 不要依赖 `endpoints` 数组位置。完整响应字段和失败情况参阅 [模型 Schema 接口](/cn/api/async-tasks#model-schema)。 ## 创建视频 视频请求始终异步，不支持通过 `Prefer: wait` 改为同步等待。原生协议使用整数 `duration` 表示秒数；不要沿用 `/v1/videos` 兼容协议中的字符串 `seconds`。 ### 标准字段 | 字段 | 类型 | 必填 | 说明 | | ----------------------- | ------------ | -- | ---------------------------------------------------- | | `model` | string | 是 | 模型 ID | | `prompt` | string | 是 | 视频描述，不能为空 | | `duration` | integer/null | 否 | 视频时长，单位为秒 | | `aspect_ratio` | string/null | 否 | 宽高比，协议默认值为 `16:9` | | `resolution` | string/null | 否 | `480p`、`720p`、`1080p`、`1K`、`2K` 或 `4K` | | `size` | string/null | 否 | `{width}x{height}`，可代替 `resolution` 与 `aspect_ratio` | | `seed` | integer/null | 否 | 随机种子 | | `input_references` | array/null | 否 | 图片、视频或音频参考素材 | | `frame_images` | array/null | 否 | 首帧或尾帧图片 | | `generate_audio` | boolean/null | 否 | 是否生成音轨 | | `webhook_url` | string | 否 | HTTPS 回调地址，最长 512 字符 | | `webhook_events_filter` | string\[] | 否 | `completed`、`failed`、`cancelled` 的非空子集 | | `extra` | object/null | 否 | 模型专属扩展参数 | 参考媒体项示例： ```json theme={null} { "type": "image_url", "url": "https://example.com/reference.png" } ``` `input_references[].type` 可以是 `image_url`、`video_url` 或 `audio_url`。首尾帧使用 `frame_images`： ```json theme={null} { "frame_type": "first_frame", "image_url": { "url": "https://example.com/first-frame.png" } } ``` 标准字段集合不表示所有模型支持全部字段。`duration`、分辨率、参考媒体结构和枚举范围 必须以该模型 `/ai/v1/videos` 端点的 `request.schema` 为准。 ## 视频任务对象 创建接口先返回任务对象。任务完成后，详情接口返回以下结构： ```json theme={null} { "id": "task_01K0ABCDEF", "object": "video", "model": "wan2.6-t2v", "status": "completed", "output": [ { "index": 0, "type": "file", "b64_json": null, "content_url": "https://aihubmix.com/ai/v1/videos/task_01K0ABCDEF/content" } ], "error": null, "created_at": 1784707200, "completed_at": 1784707320, "expires_at": 1784714520 } ``` | 字段 | 类型 | 说明 | | -------------- | ------------ | -------------------------------------------- | | `id` | string | 平台任务 ID | | `object` | string | 视频任务固定为 `video` | | `model` | string | 实际使用的模型 ID | | `status` | string | 当前任务状态 | | `output` | array | 已生成的结果；尚无结果时为空数组 | | `error` | object/null | 失败信息，可含 `code`、`message` 和 `upstream_detail` | | `created_at` | integer | 创建时间，Unix 秒 | | `completed_at` | integer/null | 进入结束态的时间，Unix 秒 | | `expires_at` | integer/null | 结果过期时间，Unix 秒；任务完成前可能为空 | 视频媒体接口的 `output` 项包含 `index`、固定值 `type: "file"`、`content_url`，以及通常 为空的 `b64_json`。视频结果一般通过二进制内容端点下载。 ### 状态说明 | 状态 | 是否结束 | 说明 | | ------------- | ---- | --------------- | | `pending` | 否 | 已接收，等待执行 | | `in_progress` | 否 | 正在生成 | | `completed` | 是 | 已完成，可下载视频 | | `failed` | 是 | 已失败，原因见 `error` | | `cancelled` | 是 | 已取消 | 客户端可以每 15 秒查询一次，直到状态变为 `completed`、`failed` 或 `cancelled`。 15 秒是客户端轮询建议，不是服务端协议限制。 ## 查询视频任务 ### 查询详情 ```bash theme={null} curl https://aihubmix.com/ai/v1/videos/{task_id} \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" ``` 视频详情接口会返回任务最新状态。轮询必须使用该接口，不要使用统一任务详情代替。 ### 查询列表 创建响应丢失时，可以通过视频列表找回任务 ID： ```bash theme={null} curl "https://aihubmix.com/ai/v1/videos?limit=20&order=desc" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" ``` | 参数 | 类型 | 默认值 | 说明 | | ------- | ------- | ------ | ------------------------ | | `after` | string | - | 分页游标，使用上一页的 `next_after` | | `limit` | integer | `20` | 每页数量，最大 `100` | | `order` | string | `desc` | `asc` 为升序，其他值按 `desc` 处理 | ```json theme={null} { "object": "list", "data": [ { "id": "task_01K0ABCDEF", "object": "video", "model": "wan2.6-t2v", "status": "in_progress", "output": [], "error": null, "created_at": 1784707200, "completed_at": null, "expires_at": null } ], "has_more": true, "next_after": "task_01K0ABCDEF" } ``` 列表返回查询时的任务快照，不会主动更新活动任务状态。 ## 统一任务接口 `/ai/v1/tasks` 提供图片、视频和 LLM 任务的统一只读视图。可以只查询视频任务： ```bash theme={null} curl "https://aihubmix.com/ai/v1/tasks?object=video&status=completed&limit=20&order=desc" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" ``` 统一任务列表支持 `object`、`status`、`model`、`after`、`limit` 和 `order`。统一任务详情： ```bash theme={null} curl https://aihubmix.com/ai/v1/tasks/{task_id} \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" ``` 统一任务中的视频结果会额外提供 `result_id` 和 `content_type`： ```json theme={null} { "index": 0, "result_id": "result_01K0XYZ", "type": "file", "content_type": "video/mp4", "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content" } ``` 单产物可以请求 `/ai/v1/tasks/{id}/content`。若统一任务包含多个结果，则请求 `/ai/v1/tasks/{id}/content/{result_id}`；未指定结果 ID 时返回 `400 result_id_required`。 媒体详情接口可能在查询时更新活动任务状态，统一任务接口只返回当前快照。因此轮询使用 `/ai/v1/videos/{id}`；统一筛选和读取结果元数据时使用 `/ai/v1/tasks`。 任务及内容按创建任务时的 Bearer Token 隔离。 ## 下载视频结果 任务进入 `completed` 后，请求视频内容端点： ```bash theme={null} curl https://aihubmix.com/ai/v1/videos/{task_id}/content \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ --output result.mp4 ``` 响应为视频二进制，不是 JSON。也可以直接请求任务对象返回的 `output[].content_url`； 两种方式都需要携带创建任务时的 Bearer Token。 结果可能过期，也可能存在下载次数限制。过期返回 `410 artifact_expired`；超过下载 次数限制返回 `429 too_many_downloads`。客户端应在任务完成后及时保存视频。 ## Webhook 创建视频任务时可以同时设置任务级 Webhook： ```bash theme={null} curl -X POST https://aihubmix.com/ai/v1/videos \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.6-t2v", "prompt": "A tranquil garden at sunrise", "duration": 5, "size": "1280x720", "webhook_url": "https://example.com/webhooks/aihubmix" }' ``` `webhook_url` 最长 512 字符，不能指向本机、私网或其他受限地址。`wan2.6-t2v` 当前 Schema 未列出 `webhook_events_filter`，因此本例不传事件过滤器，平台默认推送 `completed`、`failed` 和 `cancelled`。只有模型 Schema 明确包含该字段时才可以设置； 显式传入时，数组不能为空、不能重复，并且必须与 `webhook_url` 一起使用。 ### 回调请求 ```json theme={null} { "event_id": "evt_01K0ABCDEF", "event_type": "completed", "created_at": "2026-08-12T12:00:00Z", "data": { "task_id": "task_01K0ABCDEF", "status": "completed", "model": "wan2.6-t2v", "results": [ { "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content" } ] } } ``` `event_id` 用于去重；`data.error` 在失败时可能出现；`data.results` 只在结果已存档时出现， 下载仍需 Bearer Token。 ### 重试与去重 平台采用至少一次投递，同一个事件可能重复送达： * HTTP `2xx` 表示接收成功。 * HTTP `5xx`、网络错误或超时会触发重试。 * HTTP `3xx` 和 `4xx` 不会重试。 * 最多投递 6 次，重试间隔依次为 1、4、16、64、256 秒。 接收端应保存 `event_id`，重复收到相同事件时直接返回 `2xx`。任务级 Webhook 本身不 携带独立签名密钥；需要签名验证时，请配置账户级 Webhook，并保留详情查询作为结果确认方式。 ## 错误响应与错误码 ```json theme={null} { "error": { "message": "Task not found.", "type": "invalid_request_error", "code": "task_not_found", "tid": "req_01K0ABCDEF" } } ``` | HTTP 状态码 | 错误码 | 说明 | | -------- | ------------------------------- | ------------------------------ | | 400 | `invalid_request` | 参数类型或取值不正确 | | 400 | `schema_violation` | 请求字段不符合当前模型 Schema | | 400 | `result_id_required` | 统一任务包含多个结果，但下载时未指定 `result_id` | | 400 | `webhook_invalid` | Webhook URL 不合法，或过滤器缺少 URL | | 400 | `webhook_events_filter_invalid` | Webhook 事件列表不合法 | | 401 | `authentication_failed` | API Key 缺失或无效 | | 403 | `async_not_enabled` | 账户未开启异步任务功能 | | 404 | `task_not_found` | 任务或分页游标不存在 | | 404 | `result_not_found` | 结果不存在或当前不可下载 | | 410 | `artifact_expired` | 结果已过期 | | 413 | `request_too_large` | 请求体超过 32 MiB | | 429 | `too_many_downloads` | 超过结果下载次数限制 | `error.tid` 是请求追踪 ID，联系技术支持排查时请一并提供。 ## 完整示例 以下示例完成创建、轮询和 MP4 下载。 ```python Python theme={null} import os import time import requests base_url = "https://aihubmix.com" headers = { "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}", "Content-Type": "application/json", } response = requests.post( f"{base_url}/ai/v1/videos", headers=headers, json={ "model": "wan2.6-t2v", "prompt": "A cat playing jazz on a piano", "duration": 5, "size": "1280x720", }, timeout=60, ) response.raise_for_status() task = response.json() while task["status"] not in {"completed", "failed", "cancelled"}: time.sleep(15) response = requests.get( f"{base_url}/ai/v1/videos/{task['id']}", headers=headers, timeout=30, ) response.raise_for_status() task = response.json() if task["status"] == "completed": result = requests.get( f"{base_url}/ai/v1/videos/{task['id']}/content", headers=headers, timeout=120, ) result.raise_for_status() with open("result.mp4", "wb") as file: file.write(result.content) else: raise RuntimeError(task.get("error") or task["status"]) ``` ```typescript TypeScript theme={null} import { writeFile } from "node:fs/promises"; const baseUrl = "https://aihubmix.com"; const headers = { Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`, "Content-Type": "application/json", }; const created = await fetch(`${baseUrl}/ai/v1/videos`, { method: "POST", headers, body: JSON.stringify({ model: "wan2.6-t2v", prompt: "A cat playing jazz on a piano", duration: 5, size: "1280x720", }), }); if (!created.ok) throw new Error(await created.text()); let task = await created.json(); const finished = new Set(["completed", "failed", "cancelled"]); while (!finished.has(task.status)) { await new Promise((resolve) => setTimeout(resolve, 15_000)); const polled = await fetch(`${baseUrl}/ai/v1/videos/${task.id}`, { headers }); if (!polled.ok) throw new Error(await polled.text()); task = await polled.json(); } if (task.status === "completed") { const result = await fetch(`${baseUrl}/ai/v1/videos/${task.id}/content`, { headers, }); if (!result.ok) throw new Error(await result.text()); await writeFile("result.mp4", Buffer.from(await result.arrayBuffer())); } else { throw new Error(JSON.stringify(task.error ?? task.status)); } ``` ## 常见问题 **视频任务应该查询 `/ai/v1/tasks/{id}` 还是视频详情接口？** 轮询使用 `/ai/v1/videos/{id}`；统一筛选任务或读取 `result_id`、`content_type` 时使用 `/ai/v1/tasks`。 **为什么 `seconds` 报参数错误？** `/ai/v1/videos` 标准协议使用整数 `duration`，单位为秒，具体允许值由模型 Schema 决定。 **为什么 `resolution` 在部分模型中报参数错误？** 标准协议包含 `resolution` 和 `size`，具体模型会收窄字段。例如 `wan2.6-t2v` 使用 `size`，不接受 `resolution`。 **创建响应丢失后如何找回任务？** 请求 `GET /ai/v1/videos?limit=20&order=desc`，再用返回的任务 ID 查询视频详情。 **Webhook 没收到怎么办？** 确认回调地址可以公开访问并及时返回 `2xx`，然后使用视频详情接口确认最终状态。 更多跨媒体背景参阅 [异步任务](/cn/api/async-tasks)、 [Webhook 说明](/cn/api/async-tasks#webhooks) 和 [完整错误码](/cn/api/async-tasks#error-codes)。