Skip to content

Vega Video material management โ€‹

Updated

โ† 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 โ€‹

OperationMethodPathDescription
Create a materialPOST/v1/wand/vega-video-assets (action=create)Register a material, get an id
Query a materialGET/v1/wand/vega-video-assets/{id}Get status and the signed link
Delete a materialPOST/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 โ€‹

ParameterRequiredTypeDescription
actionYesStringFixed value create
urlYesStringMaterial address; must be a publicly reachable HTTP/HTTPS URL. URLs only โ€” inline Base64 is not supported
asset_typeYesStringMaterial type: Image / Video / Audio. Case-sensitive; other values are rejected
asset_nameNoStringMaterial name, for your own bookkeeping only; it does not affect how the material is referenced
group_idNoStringMaterial 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_personNoBooleanWhether 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.

ParameterTypeDescription
idStringMaterial ID, used for querying and for video-generation references
group_idStringMaterial 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_idStringEcho of the inbound X-Request-Id, for tracing. Present only when the caller sent that header

Request and response example โ€‹

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

Error codes โ€‹

ScenarioHTTPerror.code
action missing / invalid400invalid_request_error
url empty400invalid_request_error
asset_type missing / invalid400invalid_request_error
Upstream rejection (invalid parameters)400invalid_request_error
Upstream rejection (no permission)403permission_denied
Internal service failure500internal_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 โ€‹

ParameterRequiredTypeDescription
idYesStringMaterial ID (path parameter), the id returned at creation

Response parameters โ€‹

ParameterTypeDescription
idStringMaterial ID
statusStringProcessing status: WAIT (processing) / DONE (ready) / FAIL (failed)
urlStringTemporary signed download link (TOS) for the material. Present only when the upstream returns a non-empty value, usually absent during WAIT
group_idStringMaterial group ID. Present only when the upstream returns a non-empty value
messageStringFailure reason or extra note. Present only when the upstream returns a non-empty value (typically with FAIL)
request_idStringEcho of the inbound X-Request-Id. Present only when the caller sent that header

status reference โ€‹

statusMeaningRecommended handling
WAITAccepted upstream, material still processingPoll every 3โ€“5 seconds
DONEReady for video generationReference it as asset://<id> (Pro), or download via url
FAILMaterial processing failedRead message to diagnose, then re-create the material from a corrected url

Request and response examples โ€‹

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

Processing

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

Ready

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

Processing failed

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

Material does not exist

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

Error codes โ€‹

ScenarioHTTPerror.code
Path id empty (/v1/wand/vega-video-assets or /v1/wand/vega-video-assets/)400invalid_request_error
Upstream reports the material does not exist404not_found
Upstream rejection (no permission)403permission_denied
Internal service failure500internal_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 โ€‹

ParameterRequiredTypeDescription
actionYesStringFixed value delete
idConditionalStringMaterial ID, for single deletion. Either this or group_id โ€” never both
group_idConditionalStringGroup 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 โ€‹

ParameterTypeDescription
deletedBooleanAlways true (the success marker)
idStringThe deleted material ID. Present only for deletion by id
group_idStringThe deleted group ID. Present only for deletion by group_id
request_idStringEcho of the inbound X-Request-Id. Present only when the caller sent that header

Request and response examples โ€‹

Single deletion by 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 deletion by 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"
}

Deleting the same id twice

Re-submitting the same single-deletion request returns 404, meaning "already deleted".

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

Error codes โ€‹

ScenarioHTTPerror.code
action missing / invalid400invalid_request_error
Both id and group_id passed, or neither400invalid_request_error
Upstream reports the material does not exist (including repeat deletion)404not_found
Upstream rejection (no permission)403permission_denied
Internal service failure500internal_error

End-to-end example โ€‹

The following curl sequence walks the whole chain: create โ†’ query โ†’ reference in a video task โ†’ delete.

bash
# 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 โ€‹

ConstraintDetail
A material must be status=DONE before useCreation 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 onlywand-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 AppIDasset:// is a logical reference and cannot be resolved across AppIDs
The signed url expires in about 11.5 hoursThe 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 bodyThe 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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages