Vega Video 1.0 Max โ
โ 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
Vega Video 1.0 Max (wand-vega-video-1.0-max) is the flagship Vega Video version, built for camera and spatial control: during generation it constrains camera movement and spatial relationships, so camera moves, subject blocking and spatial layout come out more precise and more stable. Clips run up to 30 seconds, duration=-1 lets the model decide the length, and multi-turn follow-ups let you continue from the previous result.
Allowlist registration required
1.0 Max can only be called after allowlisting. Contact the WAND team to be registered.
Model overview โ
Positioning โ
Vega Video comes in three tiers โ Lite, Pro and Max โ all generally available:
| Tier | Positioning | Key strengths | Best for |
|---|---|---|---|
| Lite | Low cost ยท fast output | Lowest cost, best for high-volume batches; moderate quality bar, fast turnaround | Cost-sensitive customers with moderate quality needs |
| Pro | High quality ยท higher usable-take rate | Better image quality; more usable takes than Lite, fewer re-rolls | Customers who need deliverable footage and watch overall cost |
| Max | Flagship quality ยท stable in complex scenes | Precise, controllable camera moves and blocking; stronger character motion with fewer continuity errors and distortions; higher image quality and scene consistency | Customers with the highest bar for quality and delivery stability |
How to choose: pick Lite for volume, Pro for directly deliverable footage, and Max when camera moves and blocking must be precise and complex scenes must stay stable.
Advantages โ
Max constrains camera movement and spatial relationships during generation, aiming to get a usable take in one pass in complex scenes instead of re-rolling:
| Advantage | Description |
|---|---|
| Fewer re-rolls | With camera and spatial relationships constrained, the same brief needs fewer retries |
| Fewer continuity errors | Character count and character-to-seat / prop correspondence stay consistent across shots |
| Better image quality | Higher image quality and scene consistency |
With identical input, Max mainly fixes three common problems:
| Problem | Typical result from other models | Result with Max |
|---|---|---|
| Lost spatial anchor | After consecutive close-ups the desk is pushed out of frame and the two people facing each other lose their spatial relationship | The desk stays in frame and positions stay consistent across shots |
| Scene drifting with the camera | On a pull-back the turnstile is carried along as a fixed foreground, and the depth order between the people and the railing breaks | The turnstile stays in place and the blocking relative to it is clear |
| Continuity errors | Even with a blocking reference image, an extra person appears and people are matched to the wrong seats | Only the two leads remain, and their seats stay consistent across shots |
Use cases โ
| Use case | Description |
|---|---|
| Precise camera moves | Camera movement is precise and stable |
| Spatial staging | Blocking and spatial relationships stay stable |
| Storyboarding | Lock the staging first, then render the final footage |
For example, when generated videos show spatial misplacement or continuity errors, switch to 1.0 Max.
Simple shots don't need Max
For a single subject, a locked-off camera and no need to control camera moves or spatial relationships, Max's controllability brings little benefit and can even reduce expressiveness. Use 1.5 Pro or another version instead.
Recommendations โ
- Provide a reference image to define the subject's appearance. Keep its shot size, camera angle and subject position consistent with the camera setup in the prompt.
- Focus the prompt on camera movement and spatial relationships (e.g. "medium shot, slow lateral tracking"), and leave appearance to the reference image.
- Text-only generation works, but results may fall short of runs with a reference image.
Integration options โ
| Option | Description | Best for |
|---|---|---|
| Max direct | One model, one step: input goes straight to final footage, with precise camera/blocking control and fewer continuity errors | Getting final footage in one step |
| Decoupled | White-model generation (WAND-Vega-1.0-Previs) and video generation (Vega Video 1.5 Pro) as two steps on two models | Confirming layout and camera work before rendering โ see White-Model Video Generation |
The rest of this page covers "Max direct".
Basic information โ
| Item | Value |
|---|---|
model value | wand-vega-video-1.0-max |
| 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 30 seconds, or -1 (model decides), default 5 |
| Capabilities | Text-to-video / first-and-last-frame / reference-based (image, audio) |
| Not supported | Reference video (video_url), draft / final (draft_task, options.draft) |
| Max-only | Multi-turn follow-ups (options.conversation_id) |
| Allowlist | Required |
The call pattern is the same as the other versions โ submit and query share the same endpoints. Just switch the model value and add the Max-specific parameters below.
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 (first_frame / last_frame) | A last frame requires a first frame; options.asset_group_id is required |
| Reference-based | text + reference image / reference audio | Every media element must declare its role; options.asset_group_id is required when images are included |
| Multi-turn follow-up | text (optionally with reference images) + options.conversation_id | conversation_id comes from the previous 1.0 Max task's successful query result |
First/last frames and reference materials cannot be mixed in one request. Violating the combination rules returns 400 invalid_request_error at submission.
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Yes | String | Fixed value wand-vega-video-1.0-max |
content | Yes | Array[Object] | Multimodal input array with at least 1 element. Supports text / image_url / audio_url |
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 30, or -1 (model decides). Default 5 |
options | No | Object | Extension options. May be omitted entirely; omitting it or passing {} equals omitting every field |
options.asset_group_id | Conditional | String | Material group ID. Required whenever the request contains images (type=image_url, including first frame, last frame and reference images); the input images are archived into this group automatically. Max length 64 bytes. Not needed for text-only or audio-only requests |
options.conversation_id | No | String | Conversation ID for multi-turn follow-ups. Pass the conversation_id returned by the previous successful 1.0 Max task, and this run continues from that result. 1.0 Max only โ other versions return 400 |
options.return_last_frame | No | Boolean | Whether to return the last-frame image. Default false. The query result includes content.last_frame_url only if the model actually produced one |
Unsupported parameters
Reference video (type=video_url) and draft / final (type=draft_task, options.draft) are not available on 1.0 Max and return 400 invalid_request_error.
content elements โ
| Parameter | Required | Type | Description |
|---|---|---|---|
type | Yes | String | text / image_url / audio_url |
text | Conditional | String | Required and non-empty when type=text. Multiple text elements are concatenated in order, up to 204800 characters in total |
image_url | Conditional | Object | Required when type=image_url, shaped {"url": "..."}. Accepts a public HTTP/HTTPS URL or inline Base64 (data:<mediatype>;base64,<payload>) |
audio_url | Conditional | Object | Required when type=audio_url, shaped {"url": "..."}. Same URL rules as image_url |
role | Conditional | String | Media purpose. Required when type is image_url / audio_url; not used for type=text |
type and role combinations โ
type | role | Purpose |
|---|---|---|
text | Not used | Text prompt |
image_url | first_frame | First-frame image |
image_url | last_frame | Last-frame image (requires a first frame) |
image_url | reference_image | Reference image |
audio_url | reference_audio (fixed) | Reference audio |
Inline Base64 materials โ
| Item | Description |
|---|---|
| Supported mediatypes | image/jpeg, image/png, image/webp, image/bmp, image/tiff, image/gif, image/heic, image/heif, audio/mpeg, audio/wav |
| Per-material limit | After decoding, up to 10 MiB per image and 15 MiB per audio file |
| Request body limit | Up to 64 MiB per request; the part excluding inline materials must stay under 1 MiB, otherwise 413 request_too_large |
For large materials, upload them yourself first and pass the URL.
Request examples โ
Reference-based video โ
The reference image defines the subject's appearance; the prompt describes camera movement and spatial relationships. The request includes an image, so options.asset_group_id is required.
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-max",
"content": [
{"type": "text", "text": "The character in the reference image walks from the left of the frame to the right; the camera holds a medium shot and tracks slowly sideways"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.jpg"}, "role": "reference_image"}
],
"resolution": "1080P",
"ratio": "16:9",
"duration": 10,
"options": {"asset_group_id": "your-asset-group-id"}
}'Text-to-video โ
Text-only requests don't need asset_group_id.
{
"model": "wand-vega-video-1.0-max",
"content": [
{"type": "text", "text": "Two colleagues talk face to face across a desk; the camera slowly pushes in from a two-shot to a close-up of one of them, with the desk staying at the bottom of the frame"}
],
"resolution": "720P",
"ratio": "16:9",
"duration": -1
}Multi-turn follow-up โ
Continue from the previous successful task; conversation_id comes from the previous query result. Keep passing the reference image to hold the subject's appearance; since the request includes an image, options.asset_group_id is required.
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-max",
"content": [
{"type": "text", "text": "Keep the character appearance from the reference image and the current scene; change the camera to a slow pull-back"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.jpg"}, "role": "reference_image"}
],
"options": {
"conversation_id": "<conversation_id returned by the previous task>",
"asset_group_id": "your-asset-group-id"
}
}'Response โ
A successful submission returns HTTP 201 Created with status always queued. Acceptance does not mean the video is finished.
{
"id": "1300000000-wand_vega_video_1_0_max-68b7c1d4a1f2e3d4c5b6a79808192a3b-m0c",
"model": "wand-vega-video-1.0-max",
"status": "queued"
}Querying the result โ
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 | Echoes the submitted model value; it does not identify the model that actually rendered the video |
status | String | queued / running / succeeded / failed |
content.video_url | String | Temporary download URL of the video, valid for 12 hours |
content.last_frame_url | String | Last-frame image URL. Returned only when options.return_last_frame=true and the model produced one |
resolution / ratio / duration | โ | Actual resolution, aspect ratio and duration; may be returned only when status=succeeded. With duration=-1 the actual length is returned |
conversation_id | String | Conversation ID. Pass it as options.conversation_id in the next follow-up |
tokenhub_usage.total_tokens | Integer | Total tokens consumed (input + output). May be returned only when status=succeeded |
error.code | String | Task-level error code: InternalError / TaskTimeout / InvalidParameter; returned only when status=failed |
error.message | String | Failure reason |
{
"id": "1300000000-wand_vega_video_1_0_max-68b7c1d4a1f2e3d4c5b6a79808192a3b-m0c",
"model": "wand-vega-video-1.0-max",
"status": "succeeded",
"content": {"video_url": "https://aigc-video.example.com/xxx/result.mp4"},
"resolution": "1080P",
"ratio": "16:9",
"duration": 10,
"conversation_id": "conv-xxxxxxxx",
"tokenhub_usage": {"total_tokens": 14400}
}Poll every 3โ5 seconds until status is succeeded or failed, and save the result before the URL expires.
Error codes โ
The error-code vocabulary is shared with the other versions and the material APIs โ see the unified error codes on the overview page. 400 triggers specific to 1.0 Max:
| Trigger | Fix |
|---|---|
Passing type=video_url, type=draft_task or options.draft | Remove the unsupported element / field |
Request contains images but no options.asset_group_id | Add a material group ID |
| Mixing first/last frames with reference materials, or a last frame alone | Use one or the other; pair a last frame with a first frame |
Passing options.conversation_id to another version | Multi-turn follow-ups are wand-vega-video-1.0-max only |