Vega Video HOT
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks认证: Tokenhub API Key / Bearer
Vega Video 是 WAND 自研的视频生成模型,支持文生视频、首尾帧生视频,以及参考图片、视频、音频混合输入的多模态参考生成。七个 model 取值共用同一套提交与查询接口,Pro 系列额外支持 asset:// 素材引用;Pro 系列与 1.0 Max 支持模型自定时长(duration=-1)。
版本分 Lite / Pro / Max 三档:批量跑量选 Lite,可直接交付的成片选 Pro,运镜走位要求精确、复杂场景要求稳定选 Max。
选择版本
接口文档按版本拆分,点击卡片查看对应版本的输入规格、请求参数、请求示例与特殊设置。
wand-vega-video-1.0-max- 480P~4K,单条 4~30 秒,或
-1 - 运镜、走位精确可控,穿帮更少
- 支持多轮追问
conversation_id - 需白名单登记
wand-vega-video-1.5-pro- 480P~4K,单条 4~30 秒
- 支持
duration=-1由模型定时长 - 支持
asset://素材引用 - 需白名单登记
wand-vega-video-1.5-lite- 480P~4K,单条 2~30 秒
- 时长下限低至 2 秒
- 无需白名单,开箱可用
- 不支持
asset://与-1
1.0-pro · 1.0-pro-fast · 1.0-pro-mini- 480P~4K,单条 4~15 秒
- 标准、快速与 Mini 三种版本
- 支持
asset://素材引用 - 需白名单登记
wand-vega-video-1.0-lite- 480P~4K,单条 4~15 秒
- 默认分辨率 768P
- 无需白名单,开箱可用
- 不支持
asset://与-1
素材与认证
参考素材中出现人脸时,需要先把文件注册为素材再以 asset:// 引用。两篇配套文档单独拆分:
/v1/wand/vega-video-assets- 创建、查询、删除素材
- 按
group_id分组与整组删除 - 拿到
asset://<id>供 Pro 引用
/v1/wand/vega-video-liveness- 发起认证,拿 H5 人脸验证链接
- 轮询认证结果,拿
group_id - 用于
is_real_person=true素材
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 输入 | 文本 / 首尾帧 / 参考图片·视频·音频 |
| 生成方式 | 异步,通常耗时 1~3 分钟 |
| 提交任务 | POST /v1/wand/vega-videos/tasks |
| 结果查询 | GET /v1/wand/vega-videos/tasks/{id} |
| 结果字段 | content.video_url,有效期 12 小时 |
| 素材引用 | 仅 Pro 支持 asset://<id>,见素材库管理 |
各版本支持规格
| 版本 | model 取值 | 分辨率 | 时长(秒) | 白名单 |
|---|---|---|---|---|
| 1.0 Max | wand-vega-video-1.0-max | 480P / 720P / 1080P / 2K / 4K | 4~30,或 -1 | 需要 |
| 1.5 Pro | wand-vega-video-1.5-pro | 480P / 720P / 1080P / 2K / 4K | 4~30,或 -1 | 需要 |
| 1.5 Lite | wand-vega-video-1.5-lite | 480P / 720P / 1080P / 2K / 4K | 2~30 | 不需要 |
| 1.0 Pro | wand-vega-video-1.0-pro | 480P / 720P / 1080P / 2K / 4K | 4~15,或 -1 | 需要 |
| 1.0 Pro Fast | wand-vega-video-1.0-pro-fast | 480P / 720P / 1080P / 2K / 4K | 4~15,或 -1 | 需要 |
| 1.0 Pro Mini | wand-vega-video-1.0-pro-mini | 480P / 720P / 1080P / 2K / 4K | 4~15,或 -1 | 需要 |
| 1.0 Lite | wand-vega-video-1.0-lite | 480P / 768P / 1080P / 2K / 4K | 4~15 | 不需要 |
比例全部版本一致:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive。默认时长为 5 秒,默认比例为 adaptive(由模型或输入素材自动决定)。Pro 与 Max 的默认分辨率是 720P,1.0 Lite 是 768P。
分辨率不会自动降级
超出当前版本档位的 resolution 在提交阶段就返回 400 invalid_request_error,不会降级到相近档位。例如 1.0 Lite 没有 720P 这一档,传了会直接被拒。
duration=-1 表示由模型决定时长,Pro 系列四个版本与 1.0 Max 支持;1.0 Lite 与 1.5 Lite 不支持。
1.0 Max 的输入差异
1.0 Max 不支持参考视频(video_url)与样片 / 正片(draft_task、options.draft);请求含图片时须传 options.asset_group_id;独有多轮追问 options.conversation_id。详见 1.0 Max 接口文档。
接入准备
使用前须知
Pro 系列(1.0-pro / 1.0-pro-fast / 1.0-pro-mini / 1.5-pro)与 1.0 Max(1.0-max)需开通白名单后才能调用,请联系 WAND 团队登记。Lite 系列无需白名单。素材库管理功能需要单独的访问权限。
| 步骤 | 说明 |
|---|---|
| 开通服务 | 注册腾讯云账号并开通 TokenHub 服务 |
| 获取 API Key | 在 TokenHub 控制台创建,见获取 API Key |
| 鉴权方式 | 请求头 Authorization: Bearer YOUR_API_KEY |
| 链路追踪 | 可选传 X-Request-Id 请求头,响应会原样回显 |
本页及子页示例中的 YOUR_API_KEY 均需替换为自己的 API Key。
调用流程
视频生成是耗时任务,接口采用异步模式,统一分两步:
- 提交任务:
POST /v1/wand/vega-videos/tasks,成功返回HTTP 201与id、status=queued。 - 轮询结果:以
3~5 秒间隔调用GET /v1/wand/vega-videos/tasks/{id},直到status为succeeded或failed。成功后从content.video_url下载视频。
提交接口不做幂等
重复提交同一请求会签发新的任务 ID,可能导致重复出片与重复计费。拿到任务 ID 之后请只查询该任务,不要重新提交;重试请以业务侧请求标识自行去重。
接入场景
参考素材中是否包含真人人脸,决定了调用链的长度。三条链路如下:
| 场景 | 适用素材 | 调用链 | 参考文档 |
|---|---|---|---|
| ① 通用生视频 | 不含人脸的素材,或纯文本 / 首尾帧生成 | 创建生视频任务 → 查询任务结果 | 各版本接口文档(见上方版本卡片) |
| ② 非真人素材 | 非真人、虚拟人、卡通角色等 | 创建素材 → 查询素材 → 创建生视频任务 → 查询任务结果 | 素材库管理 |
| ③ 真人素材 | 现实真人人像 | 发起活体认证 → 查询认证结果 → 创建真人素材 → 查询素材 → 创建生视频任务 → 查询任务结果 | 活体认证 + 素材库管理 |
场景 ② 与 ③ 的差别只有两点:真人素材的 group_id 必须来自活体认证返回值,且创建素材时 is_real_person 传 true。
批量与短剧场景建议
素材是否含人脸往往难以可靠判断,建议每个参考素材都先注册再引用,不要逐张判断后再决定走哪条路径。同一人物会在多个任务中反复出现时,缓存 id 并复用,无需每次重新注册。
asset:// 引用是 Pro 专属:wand-vega-video-1.0-lite 与 wand-vega-video-1.5-lite 传入会报 Input ImageUrl domain may be contain innerip。如需 Lite 使用同一素材,请用素材查询接口拿到 url 后直接传该公网地址。
统一错误码
HTTP 区分请求错误与异步任务失败。HTTP 错误查看响应中的 error,生成任务失败查看查询结果中的 status 与 error。两者共用同一套 error.code 词表。
{
"error": {"code": "<错误码>", "message": "<错误描述>"},
"request_id": "<回显入站 X-Request-Id;未传该请求头时字段缺省>"
}| HTTP 状态 | error.code | 触发条件与处理 |
|---|---|---|
400 | invalid_request_error | 缺少必填项、类型错误、枚举越界、JSON 解析失败。对照各版本文档检查取值范围 |
401 | 由网关定义 | Authorization 头缺失或 API Key 无效 / 已过期。该错误在网关层返回,错误码以网关为准 |
403 | permission_denied | AppId 未开通相应能力(含素材库权限)。联系对接人开通 |
404 | not_found | 任务或素材 ID 不存在、路径错误、素材已被删除 |
413 | request_too_large | 请求体超过 1MiB(POST 路由),或上游响应体超过 1MiB |
500 | internal_error | 服务内部故障。若已拿到任务 ID,请先查询已有任务而不是重新提交 |
503 | service_unavailable | 服务过载。退避后重试,message 为 service overloaded |
任务级错误码(出现在查询结果的 error.code)另有 InternalError、TaskTimeout 等,error.message 给出失败原因。
1MiB 是请求体上限,不是素材文件上限
1MiB 限制的是素材管理 API 的 JSON 请求体与响应体大小,与通过 URL 注册的图片·视频·音频文件本身的容量无关。
常见问题
传入不支持的 resolution 会降级吗? 不会。超出当前版本档位的 resolution 在提交阶段直接返回 400 invalid_request_error(如 1.0 Lite 传 720P)。
生成结果视频链接会过期吗? 会。content.video_url 为临时地址,有效期 12 小时,请在任务成功后及时下载并转存到自有存储。素材查询返回的 url 有效期约 11.5 小时,是另一个地址,两者不能互换使用。
提交成功但一直处于 queued 怎么办? 排队超时的任务会被置为 failed 并返回 error.code = TaskTimeout。若长时间停留在 queued,请稍后重试,并提供任务 id 与查询响应联系技术支持。
同一素材能同时给 Pro 和 Lite 用吗? 可以,但引用方式不同。Pro 传 asset://<id>,Lite 必须传素材查询接口返回的 url(或原始公网 URL)。素材与生视频请求必须属于同一个 AppID。