Skip to content

Vega Video HOT โ€‹

Updated

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasksAuthentication: Tokenhub API Key / Bearer

Vega Video is WAND's in-house video generation model, supporting text-to-video, first-and-last-frame generation, and multimodal reference generation that mixes reference images, video, and audio. All seven model values share the same submit and query endpoints. The Pro series additionally supports asset:// material references; the Pro series and 1.0 Max support model-decided duration (duration=-1).

Versions come in three tiers โ€” Lite / Pro / Max: 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.

Choose a version โ€‹

The API reference is split per version. Open a card to see that version's input limits, request parameters, examples, and version-specific behaviour.

Materials and verification โ€‹

When a reference material contains a human face, the file must first be registered as a material and then referenced via asset://. The two companion guides are split out:

Basic information โ€‹

ItemValue
Access pathTokenhub API
InputText / first-and-last frame / reference image, video, audio
Generation modeAsynchronous, typically 1โ€“3 minutes
Submit taskPOST /v1/wand/vega-videos/tasks
Query resultGET /v1/wand/vega-videos/tasks/{id}
Result fieldcontent.video_url, valid for 12 hours
Material referencePro only, asset://<id> โ€” see Material management

Supported specs by version โ€‹

Versionmodel valueResolutionDuration (s)Allowlist
1.0 Maxwand-vega-video-1.0-max480P / 720P / 1080P / 2K / 4K4โ€“30, or -1Required
1.5 Prowand-vega-video-1.5-pro480P / 720P / 1080P / 2K / 4K4โ€“30, or -1Required
1.5 Litewand-vega-video-1.5-lite480P / 720P / 1080P / 2K / 4K2โ€“30Not required
1.0 Prowand-vega-video-1.0-pro480P / 720P / 1080P / 2K / 4K4โ€“15, or -1Required
1.0 Pro Fastwand-vega-video-1.0-pro-fast480P / 720P / 1080P / 2K / 4K4โ€“15, or -1Required
1.0 Pro Miniwand-vega-video-1.0-pro-mini480P / 720P / 1080P / 2K / 4K4โ€“15, or -1Required
1.0 Litewand-vega-video-1.0-lite480P / 768P / 1080P / 2K / 4K4โ€“15Not required

Aspect ratios are identical across all versions: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive. The default duration is 5 seconds and the default ratio is adaptive (decided by the model or by the input material). Pro and Max default to 720P; 1.0 Lite defaults to 768P.

Resolution is never downgraded automatically

A resolution outside the current version's tiers is rejected at submission with 400 invalid_request_error โ€” it is not downgraded to the nearest tier. For example, 1.0 Lite has no 720P tier, so passing it fails outright.

duration=-1 means the model decides the length. The four Pro versions and 1.0 Max support it; 1.0 Lite and 1.5 Lite do not.

How 1.0 Max inputs differ

1.0 Max does not accept reference video (video_url) or draft / final (draft_task, options.draft); requests with images must pass options.asset_group_id; and it alone supports multi-turn follow-ups via options.conversation_id. See the 1.0 Max API reference.

Before you start โ€‹

Access requirements

The Pro series (1.0-pro / 1.0-pro-fast / 1.0-pro-mini / 1.5-pro) and 1.0 Max (1.0-max) require allowlist registration โ€” contact the WAND team to be registered. The Lite series needs no allowlist. Material management requires a separate access permission.

StepDescription
Enable the serviceRegister a Tencent Cloud account and enable TokenHub
Get an API KeyCreate one in the TokenHub console โ€” see Get an API Key
AuthenticationRequest header Authorization: Bearer YOUR_API_KEY
Request tracingOptionally send X-Request-Id; it is echoed back in the response

Replace YOUR_API_KEY in every example on this page and its sub-pages with your own API Key.

Call flow โ€‹

Video generation is long-running, so the API is asynchronous and always takes two steps:

  1. Submit the task: POST /v1/wand/vega-videos/tasks returns HTTP 201 with an id and status=queued.
  2. Poll the result: call GET /v1/wand/vega-videos/tasks/{id} every 3โ€“5 seconds until status is succeeded or failed. On success, download the video from content.video_url.

The submit endpoint is not idempotent

Re-submitting the same request issues a new task ID, which can produce duplicate videos and duplicate billing. Once you have a task ID, only query that task; implement your own de-duplication with a business-side request key if you need retries.

Integration paths โ€‹

Whether a reference material contains a real human face determines how long the call chain is. There are three paths:

PathApplicable materialCall chainReference
โ‘  General video generationMaterials without faces, or plain text / first-and-last-frame generationCreate task โ†’ query resultPer-version references (cards above)
โ‘ก Non-real-person materialNon-real people, virtual humans, cartoon characters, etc.Create material โ†’ query material โ†’ create task โ†’ query resultMaterial management
โ‘ข Real-person materialPhotographs of real peopleStart liveness verification โ†’ query verification โ†’ create real-person material โ†’ query material โ†’ create task โ†’ query resultLiveness verification + Material management

Paths โ‘ก and โ‘ข differ in only two respects: for real-person material the group_id must come from liveness verification, and is_real_person must be true when creating the material.

Recommendation for batch and short-drama workloads

Reliably deciding whether a material contains a face is hard, so register every reference material first and then reference it, rather than inspecting each image and branching. When the same person recurs across many tasks, cache and reuse the id instead of re-registering every time.

asset:// references are Pro only: passing one to wand-vega-video-1.0-lite or wand-vega-video-1.5-lite returns Input ImageUrl domain may be contain innerip. To use the same material with Lite, call the material query endpoint and pass the returned public url directly.

Unified error codes โ€‹

HTTP distinguishes request errors from asynchronous task failures. For HTTP errors inspect error in the response; for generation failures inspect status and error in the query result. Both share the same error.code vocabulary.

json
{
  "error": {"code": "<error code>", "message": "<error description>"},
  "request_id": "<echo of the inbound X-Request-Id; omitted when the header is absent>"
}
HTTP statuserror.codeTrigger and handling
400invalid_request_errorMissing required field, wrong type, enum out of range, JSON parse failure. Check the value ranges in the per-version reference
401Defined by the gatewayAuthorization header missing, or API Key invalid / expired. Returned at the gateway layer, so the gateway defines the code
403permission_deniedThe AppId has not been granted the capability (including material-library access). Contact your WAND representative
404not_foundTask or material ID does not exist, wrong path, or the material was deleted
413request_too_largeRequest body over 1MiB (POST routes), or upstream response body over 1MiB
500internal_errorInternal service failure. If you already hold a task ID, query the existing task instead of re-submitting
503service_unavailableService overloaded. Back off and retry; message is service overloaded

Task-level codes (in the error.code of a query result) also include InternalError and TaskTimeout, with the reason in error.message.

1MiB caps the request body, not the material file

The 1MiB limit applies to the JSON request and response bodies of the material management API. It has nothing to do with the size of the image, video, or audio file you register by URL.

FAQ โ€‹

Is an unsupported resolution downgraded? No. A resolution outside the current version's tiers is rejected at submission with 400 invalid_request_error โ€” for example 720P on 1.0 Lite.

Does the result video link expire? Yes. content.video_url is a temporary address valid for 12 hours; download and re-host it in your own storage promptly after the task succeeds. The url returned by material query is a different address valid for roughly 11.5 hours; the two are not interchangeable.

The task was accepted but stays queued โ€” what now? Tasks that time out in the queue are set to failed with error.code = TaskTimeout. If a task stays queued for a long time, retry later and contact support with the task id and the query response.

Can one material be used by both Pro and Lite? Yes, but the reference differs. Pro takes asset://<id>; Lite must take the url returned by material query (or the original public URL). Materials and video requests must belong to the same AppID.

Tokenhub API error codes

Built with VitePress ยท Deployed on Tencent EdgeOne Pages