Vega Video material management โ
โ Back to the Vega Video overview for version comparison and integration paths.
Endpoint: https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assetsAuthentication: Tokenhub API Key / Bearer
Register a publicly reachable media URL as an AIGC custom material (image / video / audio), then reference it in a video request as asset://<id>. This is a prerequisite for the Pro versions' reference capability.
Separate access permission required
Material management must be enabled separately. Without it, calls return 403 permission_denied โ contact your WAND representative.
How it closes the loop with video generation โ
The full chain is create material โ query material โ create video task โ (optionally) delete material.
Once you have the material ID, put asset://<id> into content[].image_url.url of the video request to reference an already-registered material in the generation task.
Material management is synchronous
Unlike video tasks, every material-management request returns its result immediately and creates no background task to poll. However, the content processing of a newly created material is still asynchronous: poll the query endpoint until status=DONE before referencing it.
Real-person material additionally requires liveness verification first โ use the group_id it returns to create a material with is_real_person=true.
Endpoints โ
| Operation | Method | Path | Description |
|---|---|---|---|
| Create a material | POST | /v1/wand/vega-video-assets (action=create) | Register a material, get an id |
| Query a material | GET | /v1/wand/vega-video-assets/{id} | Get status and the signed link |
| Delete a material | POST | /v1/wand/vega-video-assets (action=delete) | Delete one material or a whole group |
Deletion uses POST, not DELETE
Deletion goes through POST with action=delete, not the HTTP DELETE method. Content-Type is application/json for both request and response.
Create a material โ
Register a publicly reachable media URL into the material library. The upstream returns the material ID synchronously and processes the content asynchronously.
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
action | Yes | String | Fixed value create |
url | Yes | String | Material address; must be a publicly reachable HTTP/HTTPS URL. URLs only โ inline Base64 is not supported |
asset_type | Yes | String | Material type: Image / Video / Audio. Case-sensitive; other values are rejected |
asset_name | No | String | Material name, for your own bookkeeping only; it does not affect how the material is referenced |
group_id | No | String | Material group ID. Generated by the service when omitted (format group-{YYYYmmddHHMMSS}-{4 random digits}). Pass it explicitly to put several materials into one group for bulk deletion |
is_real_person | No | Boolean | Whether this is a liveness-verified material. When true, group_id must be the group ID returned by liveness verification |
Response parameters โ
A normal response is HTTP 201 Created.
| Parameter | Type | Description |
|---|---|---|
id | String | Material ID, used for querying and for video-generation references |
group_id | String | Material group ID. When you omitted it on input, this is the service-generated value for group management. Present only when the upstream returns it |
request_id | String | Echo of the inbound X-Request-Id, for tracing. Present only when the caller sent that header |
Request and response example โ
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": "lead-character"
}'{
"id": "asset-20260914103210-5832",
"group_id": "group-20260914103200-7389",
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}Error codes โ
| Scenario | HTTP | error.code |
|---|---|---|
action missing / invalid | 400 | invalid_request_error |
url empty | 400 | invalid_request_error |
asset_type missing / invalid | 400 | invalid_request_error |
| Upstream rejection (invalid parameters) | 400 | invalid_request_error |
| Upstream rejection (no permission) | 403 | permission_denied |
| Internal service failure | 500 | internal_error |
Query a material โ
Query the current status and short-lived download link of a registered material. Creation is processed asynchronously: when the id comes back the material may still be processing, so poll until status=DONE before using it for video generation.
Endpoint: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/{id}
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
id | Yes | String | Material ID (path parameter), the id returned at creation |
Response parameters โ
| Parameter | Type | Description |
|---|---|---|
id | String | Material ID |
status | String | Processing status: WAIT (processing) / DONE (ready) / FAIL (failed) |
url | String | Temporary signed download link (TOS) for the material. Present only when the upstream returns a non-empty value, usually absent during WAIT |
group_id | String | Material group ID. Present only when the upstream returns a non-empty value |
message | String | Failure reason or extra note. Present only when the upstream returns a non-empty value (typically with FAIL) |
request_id | String | Echo of the inbound X-Request-Id. Present only when the caller sent that header |
status reference โ
status | Meaning | Recommended handling |
|---|---|---|
WAIT | Accepted upstream, material still processing | Poll every 3โ5 seconds |
DONE | Ready for video generation | Reference it as asset://<id> (Pro), or download via url |
FAIL | Material processing failed | Read message to diagnose, then re-create the material from a corrected url |
Request and response examples โ
curl -sS 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/asset-20260914103210-5832' \
-H 'Authorization: Bearer YOUR_API_KEY'Processing
{
"id": "asset-20260914103210-5832",
"status": "WAIT",
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}Ready
{
"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"
}Processing failed
{
"id": "asset-20260914103210-5832",
"status": "FAIL",
"message": "download asset failed: timeout",
"request_id": "3e8c9d4a-7f02-5e13-c754-ef0gg245b88f"
}Material does not exist
{
"error": {"code": "not_found", "message": "Asset is not found"},
"request_id": "1985e859-2d86-47ce-913b-cd8cc27888bb"
}Error codes โ
| Scenario | HTTP | error.code |
|---|---|---|
Path id empty (/v1/wand/vega-video-assets or /v1/wand/vega-video-assets/) | 400 | invalid_request_error |
| Upstream reports the material does not exist | 404 | not_found |
| Upstream rejection (no permission) | 403 | permission_denied |
| Internal service failure | 500 | internal_error |
Delete a material โ
Delete one specific material, or every material in a group.
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
action | Yes | String | Fixed value delete |
id | Conditional | String | Material ID, for single deletion. Either this or group_id โ never both |
group_id | Conditional | String | Group ID, for group deletion. Either this or id โ never both |
Passing both id and group_id returns 400 (the upstream defines no precedence, so this service rejects it outright); passing neither also returns 400.
group_id deletes the entire group
Deleting by group_id affects every material in that group. To delete a single material, pass only id.
Response parameters โ
| Parameter | Type | Description |
|---|---|---|
deleted | Boolean | Always true (the success marker) |
id | String | The deleted material ID. Present only for deletion by id |
group_id | String | The deleted group ID. Present only for deletion by group_id |
request_id | String | Echo of the inbound X-Request-Id. Present only when the caller sent that header |
Request and response examples โ
Single deletion by 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 deletion by 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"
}Deleting the same id twice
Re-submitting the same single-deletion request returns 404, meaning "already deleted".
{
"error": {"code": "not_found", "message": "Asset not found"},
"request_id": "5d0e1f6c-9h24-7g35-e976-gh2ii467d00h"
}Error codes โ
| Scenario | HTTP | error.code |
|---|---|---|
action missing / invalid | 400 | invalid_request_error |
Both id and group_id passed, or neither | 400 | invalid_request_error |
| Upstream reports the material does not exist (including repeat deletion) | 404 | not_found |
| Upstream rejection (no permission) | 403 | permission_denied |
| Internal service failure | 500 | internal_error |
End-to-end example โ
The following curl sequence walks the whole chain: create โ query โ reference in a video task โ delete.
# 1. Create the material โ expect 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"
}'
# expect: {"id":"asset-20260914103210-5832","group_id":"group-20260914103200-7389"}
ASSET_ID=asset-20260914103210-5832 # replace with the id returned above
# 2. Poll until status=DONE (creation is asynchronous and may need several polls)
curl -sS "https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-video-assets/$ASSET_ID" \
-H 'Authorization: Bearer YOUR_API_KEY'
# expect: {"id":"...","status":"DONE","url":"https://tos.example.com/..."}
# 3. Reference it with asset:// in a video task (Pro only; same AppId as the material)
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": "The subject slowly turns to face the camera as sunlight falls across the frame."},
{"type": "image_url", "image_url": {"url": "asset://asset-20260914103210-5832"}, "role": "reference_image"}
],
"resolution": "1080P",
"ratio": "16:9",
"duration": 5
}'
# expect: {"id":"1300000000-video-...","model":"wand-vega-video-1.0-pro","status":"queued"}
# 4. Delete the material โ expect 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"}'
# expect: {"deleted":true,"id":"asset-20260914103210-5832"}
# 5. Delete it again โ expect 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"}'
# expect: HTTP/1.1 404 Not Found + {"error":{"code":"not_found","message":"Asset not found"}}Things to watch out for โ
| Constraint | Detail |
|---|---|
A material must be status=DONE before use | Creation is asynchronous: the upstream returns the id synchronously while the content is processed in the background. The status may still be WAIT when you receive the id, and a video request at that point fails. Poll until DONE before referencing it |
asset:// references are Pro only | wand-vega-video-1.0-lite and wand-vega-video-1.5-lite do not accept asset:// URLs โ they return Input ImageUrl domain may be contain innerip. For Lite, pass the public url returned by the query endpoint instead |
| Material and video request must share one AppID | asset:// is a logical reference and cannot be resolved across AppIDs |
The signed url expires in about 11.5 hours | The url returned by query is a temporary TOS signed address; use the returned host and signature query string verbatim. It is a different address from the content.video_url of a video result (valid for 12 hours) |
1MiB caps the request body | The POST request and response bodies of the material management API are capped at 1MiB each. This is unrelated to the size of the media file you register by URL |
Unified error codes โ
The error-code vocabulary is shared with the video-generation endpoints โ see the unified error codes on the overview page.