Vega Video 1.0 Pro โ
โ Back to the Vega Video overview for version comparison and selection.
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasksAuthentication: Tokenhub API Key / Bearer
This page covers all three variants of the 1.0 Pro series: standard wand-vega-video-1.0-pro, fast wand-vega-video-1.0-pro-fast, and lightweight wand-vega-video-1.0-pro-mini. Their input limits, request parameters, and response shapes are identical โ only the model value differs. They differ in generation speed and cost, so pick what fits.
Allowlist registration required
The Pro series can only be called after allowlisting. Contact the WAND team to be registered.
The three variants โ
| Variant | model value | Positioning |
|---|---|---|
| Standard | wand-vega-video-1.0-pro | Quality first; the default choice |
| Fast | wand-vega-video-1.0-pro-fast | Faster output, suited to batches and previews |
| Mini | wand-vega-video-1.0-pro-mini | Lightweight tier, lower cost |
Basic information โ
| Item | Value |
|---|---|
model values | wand-vega-video-1.0-pro / wand-vega-video-1.0-pro-fast / wand-vega-video-1.0-pro-mini |
| Resolution | 480P / 720P / 1080P / 2K / 4K, default 720P |
| Ratio | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive, default adaptive |
| Duration | An integer from 4 to 15 seconds, or -1 (model decides), default 5 |
| Capabilities | Text-to-video / first-and-last-frame / reference-based |
| Material reference | Supports asset://<id> |
Input modes โ
| Mode | content composition | Condition |
|---|---|---|
| Text-to-video | type=text | At least 1 non-empty text element |
| First-and-last frame | text + image_url | At most 1 first_frame and 1 last_frame; text is required |
| Reference-based | text + image / video / audio | Every media element must declare the matching role |
| Registered material reference | text + asset://<id> | Material status must be DONE, and under the same AppID as the video request |
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Yes | String | wand-vega-video-1.0-pro / wand-vega-video-1.0-pro-fast / wand-vega-video-1.0-pro-mini |
content | Yes | Array[Object] | Multimodal input array; must contain at least 1 type=text element |
resolution | No | String | 480P / 720P / 1080P / 2K / 4K. Default 720P |
ratio | No | String | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive. Default adaptive |
duration | No | Integer | An integer from 4 to 15, or -1. Default 5 |
options | No | Object | Option bag. Can be omitted entirely; omitting it or passing {} applies all defaults |
options.return_last_frame | No | Boolean | Whether to return the last-frame image. Default false. content.last_frame_url appears only when the model actually produced a last frame |
options.return_vega_usage | No | Boolean | Whether the query endpoint returns usage statistics. Default false. When true, a successful response carries a usage block |
content elements โ
content is a union-typed array keyed by type, and the element fields are mutually exclusive. Within one element use only the content field matching its type โ never mix different media fields in the same element.
| Parameter | Required | Type | Description |
|---|---|---|---|
type | Yes | String | text / image_url / video_url / audio_url |
text | Conditional | String | Required and non-empty when type=text. Multiple text elements are concatenated in array order |
image_url | Conditional | Object | Required when type=image_url, shaped {"url": "..."} |
image_url.url | Conditional | String | Image address. Supports a public HTTP/HTTPS URL, inline Base64 (data:<mediatype>;base64,<payload>), and asset://<id> |
video_url | Conditional | Object | Required when type=video_url, shaped {"url": "..."} |
video_url.url | Conditional | String | Video address. Public HTTP/HTTPS URL only โ inline Base64 is not supported |
audio_url | Conditional | Object | Required when type=audio_url, shaped {"url": "..."} |
audio_url.url | Conditional | String | Audio address. Same URL rules as image_url |
role | Conditional | String | What the media is for. Required when type is image_url / video_url / audio_url; unused for type=text |
Valid type / role combinations โ
type | role | Purpose |
|---|---|---|
text | unused | Text prompt |
image_url | first_frame | First frame |
image_url | last_frame | Last frame |
image_url | reference_image | Reference image |
video_url | reference_video (fixed) | Reference video |
audio_url | reference_audio (fixed) | Reference audio |
role is required for all three media types; omitting it or leaving it empty is rejected.
Reference input conditions โ
| Item | Condition |
|---|---|
| First and last frames | At most 1 each. At least 1 type=text element must be present as well |
| Ratio of first/last frames | Derived from the input image when ratio is omitted; a supported ratio may also be set explicitly |
| Recommended reference mix | Up to 9 images, 3 videos, and 3 audio clips, with no more than 12 items in total |
| Audio references | Pair audio with at least 1 reference image or reference video; do not submit audio alone |
| Registered materials | Pass asset://<id> as image_url.url; the material must be DONE |
Do not apply VOD / MPS specs here
The reference counts above are recommendations for composing Tokenhub requests. Do not treat the FileInfos counts or size limits of VOD / MPS as limits for this API.
Request examples โ
Text-to-video โ
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-pro",
"content": [
{"type": "text", "text": "A woman walks down a rain-soaked neon street, cinematic camera move, natural motion."}
],
"resolution": "1080P",
"ratio": "16:9",
"duration": 10
}'First-and-last-frame generation โ
{
"model": "wand-vega-video-1.0-pro",
"content": [
{"type": "text", "text": "Transition naturally from the first frame to the last frame, keeping the lighting continuous."},
{"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
}Reference-based generation (fast variant) โ
{
"model": "wand-vega-video-1.0-pro-fast",
"content": [
{"type": "text", "text": "The character from the reference image moves naturally inside the reference video's scene, in rhythm with the music."},
{"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": "720P",
"ratio": "16:9",
"duration": -1,
"options": {"return_last_frame": true}
}Referencing a registered material โ
Material registration and query are covered in Material management; real-person material additionally requires liveness verification first.
{
"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
}Response parameters โ
A successful submission returns HTTP 201 Created with no error block. Task acceptance does not mean the video is finished.
| Parameter | Type | Description |
|---|---|---|
id | String | Task ID, used to poll task status |
model | String | Echo of the submitted model value |
status | String | Task status. Always queued on successful submission |
{
"id": "1300000000-video-68b7c1d4a1f2e3d4c5b6a79808192a3b4c5d6e7f8-0000",
"model": "wand-vega-video-1.0-pro",
"status": "queued"
}Querying task results โ
Endpoint: 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'| Parameter | Type | Description |
|---|---|---|
id | String | Task ID |
model | String | Echo of the submitted model value โ not an identifier of the model that actually produced the result |
status | String | queued / running / succeeded / failed |
content | Object | Generation result, returned only when status=succeeded |
content.video_url | String | Temporary download address of the finished video, valid for 12 hours |
content.last_frame_url | String | Last-frame image address. Returned only when options.return_last_frame=true and the model actually produced a last frame |
usage | Object | Token usage statistics. Returned only when options.return_vega_usage=true was submitted and status=succeeded |
usage.completion_tokens | Integer | Tokens consumed by output (video generation) |
usage.total_tokens | Integer | Total tokens consumed by the task (input + output) |
error | Object | Failure details, returned only when status=failed |
error.code | String | Task-level error code, e.g. InternalError / TaskTimeout |
error.message | String | Failure reason |
Handling by status โ
status | Meaning | Handling |
|---|---|---|
queued | Waiting | Keep querying the same task ID every 3โ5 seconds |
running | Generating | Keep querying the same task ID |
succeeded | Done | Download the result and stop querying |
failed | Failed | Read error to diagnose, then stop querying |
{
"id": "1300000000-video-68b7c1d4a1f2e3d4c5b6a79808192a3b4c5d6e7f8-0000",
"model": "wand-vega-video-1.0-pro",
"status": "succeeded",
"content": {
"video_url": "https://aigc-video.example.com/xxx/result.mp4"
}
}Re-host the result before the URL expires. Tasks that time out while waiting return failed with TaskTimeout.
Error codes โ
The error-code vocabulary is shared with the other versions and the material API โ see the unified error codes on the overview page.