Vega Video 素材库管理
← 返回 Vega Video 概览,查看版本对比与接入场景。
Endpoint: https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets认证: Tokenhub API Key / Bearer
把一个外网可访问的媒体 URL 注册为 AIGC 自定义素材(图片 / 视频 / 音频),拿到素材 ID 后在生视频请求里以 asset://<id> 引用。这是 Pro 版本引用能力的前置依赖。
需要单独的访问权限
素材库管理功能需要单独开通。未开通时调用返回 403 permission_denied,请联系对接人。
与生视频的闭环关系
完整链路:建素材 → 查素材 → 创建生视频任务 →(可选)删素材。
拿到素材 ID 后,在生视频请求的 content[].image_url.url 里填 asset://<id>,即可把已入库素材直接引用到视频生成任务里。
素材管理是同步调用
与视频任务不同,素材管理的每次请求立即返回结果,不产生需要轮询的后台任务。但创建后的素材内容处理仍是异步的,需通过查询接口轮询到 status=DONE 才可引用。
真人人像素材还需先完成活体认证,用认证返回的 group_id 创建 is_real_person=true 的素材。
接口列表
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 创建素材 | POST | /v1/wand/vega-video-assets(action=create) | 注册素材,获取 id |
| 查询素材 | GET | /v1/wand/vega-video-assets/{id} | 获取状态与签名链接 |
| 删除素材 | POST | /v1/wand/vega-video-assets(action=delete) | 单删或整组删 |
删除用 POST,不是 DELETE
删除操作走 POST + action=delete,不是 HTTP DELETE 方法。请求与响应的 Content-Type 均为 application/json。
创建素材
将一个外网可访问的媒体 URL 注册到素材库。上游同步返回素材 ID,异步处理素材内容。
接口: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets
输入参数
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
action | 是 | String | 固定为 create |
url | 是 | String | 素材地址,需外网可访问的 HTTP/HTTPS URL。仅支持 URL,不支持 Base64 内联 |
asset_type | 是 | String | 素材类型:Image / Video / Audio。区分大小写,其他值被拒绝 |
asset_name | 否 | String | 素材名称,仅用于管理标注,不影响引用方式 |
group_id | 否 | String | 素材所属分组 ID。缺省时由服务自动生成(格式 group-{YYYYmmddHHMMSS}-{4位随机数字})。显式传入可将多个素材归为同一分组,便于整组删除 |
is_real_person | 否 | Boolean | 是否为活体认证素材。为 true 时 group_id 须为活体认证接口返回的分组 ID |
输出参数
正常响应为 HTTP 201 Created。
| 参数名 | 类型 | 说明 |
|---|---|---|
id | String | 素材 ID,用于后续查询与生视频引用 |
group_id | String | 素材分组 ID。缺省传入时为服务生成值,供调用方按组管理。仅在上游返回时出现 |
request_id | String | 回显入站 X-Request-Id,用于链路追踪。仅在调用方传了该请求头时出现 |
请求和响应示例
curl -sS -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"action": "create",
"url": "https://example.com/character.jpg",
"asset_type": "Image",
"asset_name": "主角形象"
}'{
"id": "asset-20260914103210-5832",
"group_id": "group-20260914103200-7389",
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}错误码
| 错误场景 | HTTP | error.code |
|---|---|---|
action 缺失 / 非法值 | 400 | invalid_request_error |
url 为空 | 400 | invalid_request_error |
asset_type 缺失 / 非法值 | 400 | invalid_request_error |
| 上游拒绝(参数非法) | 400 | invalid_request_error |
| 上游拒绝(无操作权限) | 403 | permission_denied |
| 服务内部故障 | 500 | internal_error |
查询素材
查询已注册素材的当前状态与短效下载链接。创建是异步处理的,id 返回时素材可能仍在处理中,需轮询至 status=DONE 才可用于生视频。
接口: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/{id}
输入参数
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
id | 是 | String | 素材 ID(路径参数),即创建时返回的 id |
输出参数
| 参数名 | 类型 | 说明 |
|---|---|---|
id | String | 素材 ID |
status | String | 处理状态:WAIT(处理中)/ DONE(就绪)/ FAIL(失败) |
url | String | 素材的临时签名下载链接(TOS)。仅在上游返回非空值时出现,WAIT 期间通常不出现 |
group_id | String | 素材分组 ID。仅在上游返回非空值时出现 |
message | String | 处理失败原因或附加说明。仅在上游返回非空值时出现(通常见于 FAIL) |
request_id | String | 回显入站 X-Request-Id。仅在调用方传了该请求头时出现 |
status 状态说明
status | 含义 | 处理建议 |
|---|---|---|
WAIT | 上游已受理,素材处理中 | 每 3~5 秒 轮询一次 |
DONE | 素材就绪,可用于生视频 | 用 asset://<id> 引用(Pro),或通过 url 下载 |
FAIL | 素材处理失败 | 读取 message 定位原因,按新 url 重新创建素材 |
请求和响应示例
curl -sS 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/asset-20260914103210-5832' \
-H 'Authorization: Bearer YOUR_API_KEY'处理中
{
"id": "asset-20260914103210-5832",
"status": "WAIT",
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}就绪
{
"id": "asset-20260914103210-5832",
"status": "DONE",
"url": "https://tos.example.com/assets/xxx.jpg?X-Tos-Expires=41400&X-Tos-Signature=...",
"group_id": "group-20260914103200-7389",
"request_id": "2f7a8b3c-5e91-4d02-b643-de9ff134a77e"
}处理失败
{
"id": "asset-20260914103210-5832",
"status": "FAIL",
"message": "download asset failed: timeout",
"request_id": "3e8c9d4a-7f02-5e13-c754-ef0gg245b88f"
}素材不存在
{
"error": {"code": "not_found", "message": "Asset is not found"},
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}错误码
| 错误场景 | HTTP | error.code |
|---|---|---|
路径 id 为空(/v1/wand/vega-video-assets 或 /v1/wand/vega-video-assets/) | 400 | invalid_request_error |
| 上游报素材不存在 | 404 | not_found |
| 上游拒绝(无操作权限) | 403 | permission_denied |
| 服务内部故障 | 500 | internal_error |
删除素材
删除指定素材(单删)或整个分组下的全部素材(按组删)。
接口: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets
输入参数
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
action | 是 | String | 固定为 delete |
id | 条件必填 | String | 素材 ID,单删时填写。与 group_id 二选一,不可同时填写 |
group_id | 条件必填 | String | 分组 ID,按组删时填写。与 id 二选一,不可同时填写 |
id 与 group_id 都传 → 400(上游未定义同时传的优先级,本服务主动拒绝);都不传 → 400。
传 group_id 会删掉整组素材
按 group_id 删除会作用于该分组下的所有素材。只想删单个素材时,只传 id。
输出参数
| 参数名 | 类型 | 说明 |
|---|---|---|
deleted | Boolean | 固定为 true(删除成功的标志) |
id | String | 被删除的素材 ID。仅在按 id 删除时出现 |
group_id | String | 被删除的分组 ID。仅在按 group_id 删除时出现 |
request_id | String | 回显入站 X-Request-Id。仅在调用方传了该请求头时出现 |
请求和响应示例
按 id 单删
curl -sS -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{"action": "delete", "id": "asset-20260914103210-5832"}'{
"deleted": true,
"id": "asset-20260914103210-5832",
"request_id": "4c9d0e5b-8g13-6f24-d865-fg1hh356c99g"
}按 group_id 整组删
curl -sS -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{"action": "delete", "group_id": "group-20260914103200-7389"}'{
"deleted": true,
"group_id": "group-20260914103200-7389",
"request_id": "5d0e1f6c-9h24-7g35-e976-gh2ii467d00h"
}重复删同一 id
重复提交同一单删请求会得到 404,表示「已删除」。
{
"error": {"code": "not_found", "message": "Asset not found"},
"request_id": "5d0e1f6c-9h24-7g35-e976-gh2ii467d00h"
}错误码
| 错误场景 | HTTP | error.code |
|---|---|---|
action 缺失 / 非法值 | 400 | invalid_request_error |
id 和 group_id 都传或都不传 | 400 | invalid_request_error |
| 上游报素材不存在(含重复删) | 404 | not_found |
| 上游拒绝(无操作权限) | 403 | permission_denied |
| 服务内部故障 | 500 | internal_error |
完整调用示例
以下 curl 串联了「建 → 查 → 生视频引用 → 删」完整链路。
# 1. 建素材 → 期望 201 + id
curl -sS -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"action": "create",
"url": "https://example.com/character.jpg",
"asset_type": "Image",
"asset_name": "e2e-test"
}'
# 期望:{"id":"asset-20260914103210-5832","group_id":"group-20260914103200-7389"}
ASSET_ID=asset-20260914103210-5832 # 替换为上一步返回的 id
# 2. 轮询直至 status=DONE(创建是异步处理的,可能需轮询若干次)
curl -sS "https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/$ASSET_ID" \
-H 'Authorization: Bearer YOUR_API_KEY'
# 期望:{"id":"...","status":"DONE","url":"https://tos.example.com/..."}
# 3. 用 asset:// 引用生视频(Pro 专属;必须与素材同一 AppId)
curl -sS -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-pro",
"content": [
{"type": "text", "text": "画面中的人物缓缓转头看向镜头,阳光洒落"},
{"type": "image_url", "image_url": {"url": "asset://asset-20260914103210-5832"}, "role": "reference_image"}
],
"resolution": "1080P",
"ratio": "16:9",
"duration": 5
}'
# 期望:{"id":"1300000000-video-...","model":"wand-vega-video-1.0-pro","status":"queued"}
# 4. 删素材 → 期望 200 + deleted:true
curl -sS -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{"action": "delete", "id": "asset-20260914103210-5832"}'
# 期望:{"deleted":true,"id":"asset-20260914103210-5832"}
# 5. 重复删 → 期望 404
curl -sS -i -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{"action": "delete", "id": "asset-20260914103210-5832"}'
# 期望:HTTP/1.1 404 Not Found + {"error":{"code":"not_found","message":"Asset not found"}}注意事项
| 约束 | 说明 |
|---|---|
素材须 status=DONE 才可用于生视频 | 创建接口是异步处理的:上游同步返回 id,但素材内容在后台处理。拿到 id 时 status 可能仍为 WAIT,此时发起生视频请求会报错。请轮询到 DONE 再引用 |
asset:// 引用是 Pro 专属 | wand-vega-video-1.0-lite 与 wand-vega-video-1.5-lite 不支持 asset:// 形式的 URL,传入会报 Input ImageUrl domain may be contain innerip。Lite 请改用查询接口返回的 url 直接传公网地址 |
| 素材与生视频须同一 AppID | asset:// 是逻辑引用,跨 AppID 无法解析 |
签名 url 约 11.5 小时过期 | 查询返回的 url 是 TOS 临时签名地址,请原样使用返回的主机与签名查询串。它与生视频结果的 content.video_url(有效期 12 小时)是两个不同的地址 |
1MiB 是请求体上限 | 素材管理 API 的 POST 请求体与响应大小上限各为 1MiB,与通过 URL 注册的媒体文件本身容量无关 |
统一错误码
错误码词表与视频生成接口共用,见概览页的统一错误码。