Skip to main content
AIHubMix 原生视频协议使用 /ai/v1/videos 系列端点。视频生成固定异步,请求提交后返回 任务 ID,客户端轮询详情或接收 Webhook,完成后下载视频。
使用原生视频任务接口前,需要为当前账户开启异步任务功能。未开启时,任务创建请求返回 403 async_not_enabled

快速开始

下面使用 wan2.6-t2v 创建一个 5 秒视频。

接口概览

Base URL:https://aihubmix.com 认证方式:

查询模型 Schema

模型目录可以筛选已经提供请求 Schema 的文生视频模型:
取得 model_id 后,查询该模型实际支持的端点:
同一模型可能同时返回 AIHubMix 原生与 OpenAI 兼容端点。应按 path 选择原生视频接口, 再读取对应的 request.schema
不要依赖 endpoints 数组位置。完整响应字段和失败情况参阅 模型 Schema 接口

创建视频

视频请求始终异步,不支持通过 Prefer: wait 改为同步等待。原生协议使用整数 duration 表示秒数;不要沿用 /v1/videos 兼容协议中的字符串 seconds

标准字段

参考媒体项示例:
input_references[].type 可以是 image_urlvideo_urlaudio_url。首尾帧使用 frame_images
标准字段集合不表示所有模型支持全部字段。duration、分辨率、参考媒体结构和枚举范围 必须以该模型 /ai/v1/videos 端点的 request.schema 为准。

视频任务对象

创建接口先返回任务对象。任务完成后,详情接口返回以下结构:
视频媒体接口的 output 项包含 index、固定值 type: "file"content_url,以及通常 为空的 b64_json。视频结果一般通过二进制内容端点下载。

状态说明

客户端可以每 15 秒查询一次,直到状态变为 completedfailedcancelled。 15 秒是客户端轮询建议,不是服务端协议限制。

查询视频任务

查询详情

视频详情接口会返回任务最新状态。轮询必须使用该接口,不要使用统一任务详情代替。

查询列表

创建响应丢失时,可以通过视频列表找回任务 ID:
列表返回查询时的任务快照,不会主动更新活动任务状态。

统一任务接口

/ai/v1/tasks 提供图片、视频和 LLM 任务的统一只读视图。可以只查询视频任务:
统一任务列表支持 objectstatusmodelafterlimitorder。统一任务详情:
统一任务中的视频结果会额外提供 result_idcontent_type
单产物可以请求 /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 后,请求视频内容端点:
响应为视频二进制,不是 JSON。也可以直接请求任务对象返回的 output[].content_url; 两种方式都需要携带创建任务时的 Bearer Token。
结果可能过期,也可能存在下载次数限制。过期返回 410 artifact_expired;超过下载 次数限制返回 429 too_many_downloads。客户端应在任务完成后及时保存视频。

Webhook

创建视频任务时可以同时设置任务级 Webhook:
webhook_url 最长 512 字符,不能指向本机、私网或其他受限地址。wan2.6-t2v 当前 Schema 未列出 webhook_events_filter,因此本例不传事件过滤器,平台默认推送 completedfailedcancelled。只有模型 Schema 明确包含该字段时才可以设置; 显式传入时,数组不能为空、不能重复,并且必须与 webhook_url 一起使用。

回调请求

event_id 用于去重;data.error 在失败时可能出现;data.results 只在结果已存档时出现, 下载仍需 Bearer Token。

重试与去重

平台采用至少一次投递,同一个事件可能重复送达:
  • HTTP 2xx 表示接收成功。
  • HTTP 5xx、网络错误或超时会触发重试。
  • HTTP 3xx4xx 不会重试。
  • 最多投递 6 次,重试间隔依次为 1、4、16、64、256 秒。
接收端应保存 event_id,重复收到相同事件时直接返回 2xx。任务级 Webhook 本身不 携带独立签名密钥;需要签名验证时,请配置账户级 Webhook,并保留详情查询作为结果确认方式。

错误响应与错误码

error.tid 是请求追踪 ID,联系技术支持排查时请一并提供。

完整示例

以下示例完成创建、轮询和 MP4 下载。

常见问题

视频任务应该查询 /ai/v1/tasks/{id} 还是视频详情接口? 轮询使用 /ai/v1/videos/{id};统一筛选任务或读取 result_idcontent_type 时使用 /ai/v1/tasks 为什么 seconds 报参数错误? /ai/v1/videos 标准协议使用整数 duration,单位为秒,具体允许值由模型 Schema 决定。 为什么 resolution 在部分模型中报参数错误? 标准协议包含 resolutionsize,具体模型会收窄字段。例如 wan2.6-t2v 使用 size,不接受 resolution 创建响应丢失后如何找回任务? 请求 GET /ai/v1/videos?limit=20&order=desc,再用返回的任务 ID 查询视频详情。 Webhook 没收到怎么办? 确认回调地址可以公开访问并及时返回 2xx,然后使用视频详情接口确认最终状态。 更多跨媒体背景参阅 异步任务Webhook 说明完整错误码