跳到内容

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。

参数名类型说明
idString素材 ID,用于后续查询与生视频引用
group_idString素材分组 ID。缺省传入时为服务生成值,供调用方按组管理。仅在上游返回时出现
request_idString回显入站 X-Request-Id,用于链路追踪。仅在调用方传了该请求头时出现

请求和响应示例 ​

bash
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": "主角形象"
  }'
json
{
  "id": "asset-20260914103210-5832",
  "group_id": "group-20260914103200-7389",
  "request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}

错误码 ​

错误场景HTTPerror.code
action 缺失 / 非法值400invalid_request_error
url 为空400invalid_request_error
asset_type 缺失 / 非法值400invalid_request_error
上游拒绝(参数非法)400invalid_request_error
上游拒绝(无操作权限)403permission_denied
服务内部故障500internal_error

查询素材 ​

查询已注册素材的当前状态与短效下载链接。创建是异步处理的,id 返回时素材可能仍在处理中,需轮询至 status=DONE 才可用于生视频。

接口: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/{id}

输入参数 ​

参数名必选类型描述
id是String素材 ID(路径参数),即创建时返回的 id

输出参数 ​

参数名类型说明
idString素材 ID
statusString处理状态:WAIT(处理中)/ DONE(就绪)/ FAIL(失败)
urlString素材的临时签名下载链接(TOS)。仅在上游返回非空值时出现,WAIT 期间通常不出现
group_idString素材分组 ID。仅在上游返回非空值时出现
messageString处理失败原因或附加说明。仅在上游返回非空值时出现(通常见于 FAIL)
request_idString回显入站 X-Request-Id。仅在调用方传了该请求头时出现

status 状态说明 ​

status含义处理建议
WAIT上游已受理,素材处理中每 3~5 秒 轮询一次
DONE素材就绪,可用于生视频用 asset://<id> 引用(Pro),或通过 url 下载
FAIL素材处理失败读取 message 定位原因,按新 url 重新创建素材

请求和响应示例 ​

bash
curl -sS 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/asset-20260914103210-5832' \
  -H 'Authorization: Bearer YOUR_API_KEY'

处理中

json
{
  "id": "asset-20260914103210-5832",
  "status": "WAIT",
  "request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}

就绪

json
{
  "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"
}

处理失败

json
{
  "id": "asset-20260914103210-5832",
  "status": "FAIL",
  "message": "download asset failed: timeout",
  "request_id": "3e8c9d4a-7f02-5e13-c754-ef0gg245b88f"
}

素材不存在

json
{
  "error": {"code": "not_found", "message": "Asset is not found"},
  "request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}

错误码 ​

错误场景HTTPerror.code
路径 id 为空(/v1/wand/vega-video-assets 或 /v1/wand/vega-video-assets/)400invalid_request_error
上游报素材不存在404not_found
上游拒绝(无操作权限)403permission_denied
服务内部故障500internal_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。

输出参数 ​

参数名类型说明
deletedBoolean固定为 true(删除成功的标志)
idString被删除的素材 ID。仅在按 id 删除时出现
group_idString被删除的分组 ID。仅在按 group_id 删除时出现
request_idString回显入站 X-Request-Id。仅在调用方传了该请求头时出现

请求和响应示例 ​

按 id 单删

bash
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"}'
json
{
  "deleted": true,
  "id": "asset-20260914103210-5832",
  "request_id": "4c9d0e5b-8g13-6f24-d865-fg1hh356c99g"
}

按 group_id 整组删

bash
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"}'
json
{
  "deleted": true,
  "group_id": "group-20260914103200-7389",
  "request_id": "5d0e1f6c-9h24-7g35-e976-gh2ii467d00h"
}

重复删同一 id

重复提交同一单删请求会得到 404,表示「已删除」。

json
{
  "error": {"code": "not_found", "message": "Asset not found"},
  "request_id": "5d0e1f6c-9h24-7g35-e976-gh2ii467d00h"
}

错误码 ​

错误场景HTTPerror.code
action 缺失 / 非法值400invalid_request_error
id 和 group_id 都传或都不传400invalid_request_error
上游报素材不存在(含重复删)404not_found
上游拒绝(无操作权限)403permission_denied
服务内部故障500internal_error

完整调用示例 ​

以下 curl 串联了「建 → 查 → 生视频引用 → 删」完整链路。

bash
# 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 直接传公网地址
素材与生视频须同一 AppIDasset:// 是逻辑引用,跨 AppID 无法解析
签名 url 约 11.5 小时过期查询返回的 url 是 TOS 临时签名地址,请原样使用返回的主机与签名查询串。它与生视频结果的 content.video_url(有效期 12 小时)是两个不同的地址
1MiB 是请求体上限素材管理 API 的 POST 请求体与响应大小上限各为 1MiB,与通过 URL 注册的媒体文件本身容量无关

统一错误码 ​

错误码词表与视频生成接口共用,见概览页的统一错误码。

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