跳到内容

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。

选择版本 ​

接口文档按版本拆分,点击卡片查看对应版本的输入规格、请求参数、请求示例与特殊设置。

素材与认证 ​

参考素材中出现人脸时,需要先把文件注册为素材再以 asset:// 引用。两篇配套文档单独拆分:

基本信息 ​

项目值
调用路径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 Maxwand-vega-video-1.0-max480P / 720P / 1080P / 2K / 4K4~30,或 -1需要
1.5 Prowand-vega-video-1.5-pro480P / 720P / 1080P / 2K / 4K4~30,或 -1需要
1.5 Litewand-vega-video-1.5-lite480P / 720P / 1080P / 2K / 4K2~30不需要
1.0 Prowand-vega-video-1.0-pro480P / 720P / 1080P / 2K / 4K4~15,或 -1需要
1.0 Pro Fastwand-vega-video-1.0-pro-fast480P / 720P / 1080P / 2K / 4K4~15,或 -1需要
1.0 Pro Miniwand-vega-video-1.0-pro-mini480P / 720P / 1080P / 2K / 4K4~15,或 -1需要
1.0 Litewand-vega-video-1.0-lite480P / 768P / 1080P / 2K / 4K4~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。

调用流程 ​

视频生成是耗时任务,接口采用异步模式,统一分两步:

  1. 提交任务:POST /v1/wand/vega-videos/tasks,成功返回 HTTP 201 与 id、status=queued。
  2. 轮询结果:以 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 词表。

json
{
  "error": {"code": "<错误码>", "message": "<错误描述>"},
  "request_id": "<回显入站 X-Request-Id;未传该请求头时字段缺省>"
}
HTTP 状态error.code触发条件与处理
400invalid_request_error缺少必填项、类型错误、枚举越界、JSON 解析失败。对照各版本文档检查取值范围
401由网关定义Authorization 头缺失或 API Key 无效 / 已过期。该错误在网关层返回,错误码以网关为准
403permission_deniedAppId 未开通相应能力(含素材库权限)。联系对接人开通
404not_found任务或素材 ID 不存在、路径错误、素材已被删除
413request_too_large请求体超过 1MiB(POST 路由),或上游响应体超过 1MiB
500internal_error服务内部故障。若已拿到任务 ID,请先查询已有任务而不是重新提交
503service_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。

Tokenhub API 错误码

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages