Skip to content

Vega Video 1.0 Max โ€‹

Updated

โ† 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:

TierPositioningKey strengthsBest for
LiteLow cost ยท fast outputLowest cost, best for high-volume batches; moderate quality bar, fast turnaroundCost-sensitive customers with moderate quality needs
ProHigh quality ยท higher usable-take rateBetter image quality; more usable takes than Lite, fewer re-rollsCustomers who need deliverable footage and watch overall cost
MaxFlagship quality ยท stable in complex scenesPrecise, controllable camera moves and blocking; stronger character motion with fewer continuity errors and distortions; higher image quality and scene consistencyCustomers 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:

AdvantageDescription
Fewer re-rollsWith camera and spatial relationships constrained, the same brief needs fewer retries
Fewer continuity errorsCharacter count and character-to-seat / prop correspondence stay consistent across shots
Better image qualityHigher image quality and scene consistency

With identical input, Max mainly fixes three common problems:

ProblemTypical result from other modelsResult with Max
Lost spatial anchorAfter consecutive close-ups the desk is pushed out of frame and the two people facing each other lose their spatial relationshipThe desk stays in frame and positions stay consistent across shots
Scene drifting with the cameraOn a pull-back the turnstile is carried along as a fixed foreground, and the depth order between the people and the railing breaksThe turnstile stays in place and the blocking relative to it is clear
Continuity errorsEven with a blocking reference image, an extra person appears and people are matched to the wrong seatsOnly the two leads remain, and their seats stay consistent across shots

Use cases โ€‹

Use caseDescription
Precise camera movesCamera movement is precise and stable
Spatial stagingBlocking and spatial relationships stay stable
StoryboardingLock 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 โ€‹

OptionDescriptionBest for
Max directOne model, one step: input goes straight to final footage, with precise camera/blocking control and fewer continuity errorsGetting final footage in one step
DecoupledWhite-model generation (WAND-Vega-1.0-Previs) and video generation (Vega Video 1.5 Pro) as two steps on two modelsConfirming layout and camera work before rendering โ€” see White-Model Video Generation

The rest of this page covers "Max direct".

Basic information โ€‹

ItemValue
model valuewand-vega-video-1.0-max
Resolution480P / 720P / 1080P / 2K / 4K, default 720P
Ratio21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive, default adaptive
DurationAn integer from 4 to 30 seconds, or -1 (model decides), default 5
CapabilitiesText-to-video / first-and-last-frame / reference-based (image, audio)
Not supportedReference video (video_url), draft / final (draft_task, options.draft)
Max-onlyMulti-turn follow-ups (options.conversation_id)
AllowlistRequired

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

Modecontent compositionCondition
Text-to-videotype=textAt least 1 non-empty text element
First-and-last frametext + image_url (first_frame / last_frame)A last frame requires a first frame; options.asset_group_id is required
Reference-basedtext + reference image / reference audioEvery media element must declare its role; options.asset_group_id is required when images are included
Multi-turn follow-uptext (optionally with reference images) + options.conversation_idconversation_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 โ€‹

ParameterRequiredTypeDescription
modelYesStringFixed value wand-vega-video-1.0-max
contentYesArray[Object]Multimodal input array with at least 1 element. Supports text / image_url / audio_url
resolutionNoString480P / 720P / 1080P / 2K / 4K. Default 720P
ratioNoString21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive. Default adaptive
durationNoIntegerAn integer from 4 to 30, or -1 (model decides). Default 5
optionsNoObjectExtension options. May be omitted entirely; omitting it or passing {} equals omitting every field
options.asset_group_idConditionalStringMaterial 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_idNoStringConversation 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_frameNoBooleanWhether 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 โ€‹

ParameterRequiredTypeDescription
typeYesStringtext / image_url / audio_url
textConditionalStringRequired and non-empty when type=text. Multiple text elements are concatenated in order, up to 204800 characters in total
image_urlConditionalObjectRequired when type=image_url, shaped {"url": "..."}. Accepts a public HTTP/HTTPS URL or inline Base64 (data:<mediatype>;base64,<payload>)
audio_urlConditionalObjectRequired when type=audio_url, shaped {"url": "..."}. Same URL rules as image_url
roleConditionalStringMedia purpose. Required when type is image_url / audio_url; not used for type=text

type and role combinations โ€‹

typerolePurpose
textNot usedText prompt
image_urlfirst_frameFirst-frame image
image_urllast_frameLast-frame image (requires a first frame)
image_urlreference_imageReference image
audio_urlreference_audio (fixed)Reference audio

Inline Base64 materials โ€‹

ItemDescription
Supported mediatypesimage/jpeg, image/png, image/webp, image/bmp, image/tiff, image/gif, image/heic, image/heif, audio/mpeg, audio/wav
Per-material limitAfter decoding, up to 10 MiB per image and 15 MiB per audio file
Request body limitUp 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.

bash
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.

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

bash
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.

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

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks/<task_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
ParameterTypeDescription
idStringTask ID
modelStringEchoes the submitted model value; it does not identify the model that actually rendered the video
statusStringqueued / running / succeeded / failed
content.video_urlStringTemporary download URL of the video, valid for 12 hours
content.last_frame_urlStringLast-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_idStringConversation ID. Pass it as options.conversation_id in the next follow-up
tokenhub_usage.total_tokensIntegerTotal tokens consumed (input + output). May be returned only when status=succeeded
error.codeStringTask-level error code: InternalError / TaskTimeout / InvalidParameter; returned only when status=failed
error.messageStringFailure reason
json
{
  "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:

TriggerFix
Passing type=video_url, type=draft_task or options.draftRemove the unsupported element / field
Request contains images but no options.asset_group_idAdd a material group ID
Mixing first/last frames with reference materials, or a last frame aloneUse one or the other; pair a last frame with a first frame
Passing options.conversation_id to another versionMulti-turn follow-ups are wand-vega-video-1.0-max only

Built with VitePress ยท Deployed on Tencent EdgeOne Pages