Vega Video 1.0 Lite
← 返回 Vega Video 概览,查看版本对比与选型。
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks认证: Tokenhub API Key / Bearer
Vega Video 1.0 Lite(wand-vega-video-1.0-lite)是入门档版本,无需白名单,拿到 API Key 即可调用,适合快速验证与成本敏感的批量场景。
分辨率档位与其他版本不同
1.0 Lite 的档位是 480P / 768P / 1080P / 2K / 4K,没有 720P 这一档,默认 768P。传 720P 会在提交阶段直接返回 400 invalid_request_error,不会降级。这是本版本最常见的踩坑点。
不支持 asset:// 与 duration=-1
Lite 系列不支持 asset:// 素材引用,传入会报 Input ImageUrl domain may be contain innerip;也不支持 duration=-1。需要引用已注册素材时,请用素材查询接口返回的 url 直接传公网地址。
基本信息
| 项目 | 值 |
|---|---|
model 取值 | wand-vega-video-1.0-lite |
| 分辨率 | 480P / 768P / 1080P / 2K / 4K,默认 768P |
| 比例 | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive,默认 adaptive |
| 时长 | 4~15 秒的整数,默认 5。不支持 -1 |
| 支持能力 | 文生 / 首尾帧生 / 参考生 |
| 白名单 | 不需要 |
| 素材引用 | 不支持 asset:// |
输入方式
| 方式 | content 构成 | 条件 |
|---|---|---|
| 文生视频 | type=text | 至少 1 个非空文本元素 |
| 首尾帧生视频 | text + image_url | first_frame 最多 1 张,last_frame 最多 1 张,文本必填 |
| 参考生视频 | text + 图片·视频·音频 | 每个媒体元素必须指定对应的 role |
请求参数
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
model | 是 | String | 固定值 wand-vega-video-1.0-lite |
content | 是 | Array[Object] | 多模态输入数组,必须包含至少 1 个 type=text 元素 |
resolution | 否 | String | 480P / 768P / 1080P / 2K / 4K。默认 768P |
ratio | 否 | String | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive。默认 adaptive |
duration | 否 | Integer | 4~15 的整数。默认 5。不支持 -1 |
options | 否 | Object | 扩展选项集合。整体可缺省;未传或空对象等价于全部字段缺省 |
options.return_last_frame | 否 | Boolean | 是否返回尾帧图片。默认 false。仅在模型确实产出尾帧时,查询结果才包含 content.last_frame_url |
options.return_vega_usage | 否 | Boolean | 是否在查询接口返回用量统计。默认 false。传 true 时成功响应带 usage 块(Lite 也返回) |
content 元素
content 是按 type 区分的联合类型数组,各元素字段互斥。一个元素中只使用与 type 相符的内容字段,请勿在同一元素内混用不同媒体字段。
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
type | 是 | String | text / image_url / video_url / audio_url |
text | 条件必选 | String | type=text 时必填且不可为空串。多个文本元素按数组顺序拼接 |
image_url | 条件必选 | Object | type=image_url 时必填,结构 {"url": "..."} |
image_url.url | 条件必选 | String | 图片地址。支持公网 HTTP/HTTPS URL 与 Base64 内联(data:<mediatype>;base64,<payload>) |
video_url | 条件必选 | Object | type=video_url 时必填,结构 {"url": "..."} |
video_url.url | 条件必选 | String | 视频地址。仅支持公网 HTTP/HTTPS URL,不支持 Base64 内联 |
audio_url | 条件必选 | Object | type=audio_url 时必填,结构 {"url": "..."} |
audio_url.url | 条件必选 | String | 音频地址。URL 约束同 image_url |
role | 条件必选 | String | 媒体用途。type 为 image_url / video_url / audio_url 时必填,type=text 不使用该字段 |
type 与 role 的组合
type | role | 实际用途 |
|---|---|---|
text | 不使用 | 文本提示词 |
image_url | first_frame | 首帧图片 |
image_url | last_frame | 尾帧图片 |
image_url | reference_image | 参考图片 |
video_url | reference_video(固定) | 参考视频 |
audio_url | reference_audio(固定) | 参考音频 |
role 对三种媒体 type 均为必填,省略或留空会被拒绝。
参考输入条件
| 项目 | 条件 |
|---|---|
| 首尾帧 | 各最多 1 张。必须同时包含至少 1 个 type=text 元素 |
| 首尾帧的比例 | 省略 ratio 时由输入图片决定;也可显式指定支持的比例 |
| 推荐的参考构成 | 图片不超过 9 张、视频不超过 3 段、音频不超过 3 段,合计不超过 12 个 |
| 音频参考 | 建议至少搭配 1 个参考图片或参考视频,不要仅输入音频 |
请求示例
文生视频
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"model": "wand-vega-video-1.0-lite",
"content": [
{"type": "text", "text": "一只橙色小猫在窗台上看向镜头,阳光从侧面洒入,镜头缓缓推进"}
],
"resolution": "768P",
"ratio": "16:9",
"duration": 6
}'首尾帧生视频
{
"model": "wand-vega-video-1.0-lite",
"content": [
{"type": "text", "text": "镜头从首帧自然过渡到尾帧,保持光影连续"},
{"type": "image_url", "image_url": {"url": "https://example.com/start.jpg"}, "role": "first_frame"},
{"type": "image_url", "image_url": {"url": "https://example.com/end.jpg"}, "role": "last_frame"}
],
"resolution": "1080P",
"duration": 8
}参考生视频
{
"model": "wand-vega-video-1.0-lite",
"content": [
{"type": "text", "text": "参考图中的角色在参考视频的场景里自然运动,背景音乐与画面节奏一致"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.jpg"}, "role": "reference_image"},
{"type": "video_url", "video_url": {"url": "https://example.com/scene.mp4"}, "role": "reference_video"},
{"type": "audio_url", "audio_url": {"url": "https://example.com/bgm.mp3"}, "role": "reference_audio"}
],
"resolution": "768P",
"ratio": "16:9",
"duration": 10
}响应参数
提交成功的响应为 HTTP 201 Created,响应体中不含错误信息块。任务受理并不意味着视频生成完成。
| 参数名 | 类型 | 说明 |
|---|---|---|
id | String | 任务 ID,用于轮询查询任务状态 |
model | String | 回显提交时的 model 取值 |
status | String | 任务状态。提交成功恒为 queued |
{
"id": "1300000000-video-68b7c1d4a1f2e3d4c5b6a79808192a3b4c5d6e7f8-0000",
"model": "wand-vega-video-1.0-lite",
"status": "queued"
}任务结果查询
接口: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks/{id}
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks/<task_id>' \
-H 'Authorization: Bearer YOUR_API_KEY'| 参数名 | 类型 | 说明 |
|---|---|---|
id | String | 任务 ID |
model | String | 回显提交时的 model 取值,不是实际出片模型的标识 |
status | String | queued(排队中)/ running(生成中)/ succeeded(生成成功)/ failed(生成失败) |
content | Object | 生成结果,仅在 status=succeeded 时返回 |
content.video_url | String | 完成视频的临时下载地址,有效期 12 小时 |
content.last_frame_url | String | 尾帧图片地址。仅在 options.return_last_frame=true 且模型确实产出尾帧时返回 |
usage | Object | 用量(token)统计。仅在提交时传了 options.return_vega_usage=true 且 status=succeeded 时返回 |
usage.completion_tokens | Integer | 输出(出片)消耗的 token 数 |
usage.total_tokens | Integer | 本次任务合计消耗的 token 数(输入 + 输出) |
error | Object | 失败信息,仅在 status=failed 时返回 |
error.code | String | 任务级错误码,如 InternalError / TaskTimeout |
error.message | String | 失败原因描述 |
各状态的处理
status | 含义 | 处理 |
|---|---|---|
queued | 等待中 | 用同一任务 ID 以 3~5 秒 间隔继续查询 |
running | 生成中 | 用同一任务 ID 继续查询 |
succeeded | 完成 | 下载结果后结束查询 |
failed | 失败 | 读取 error 定位原因后结束查询 |
{
"id": "1300000000-video-68b7c1d4a1f2e3d4c5b6a79808192a3b4c5d6e7f8-0000",
"model": "wand-vega-video-1.0-lite",
"status": "succeeded",
"content": {
"video_url": "https://aigc-video.example.com/xxx/result.mp4"
}
}请在结果 URL 过期前转存。等待超时的任务会返回 failed 与 TaskTimeout。
错误码
错误码词表与其他版本、素材接口共用,见概览页的统一错误码。