Vega Video HOT โ
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.
wand-vega-video-1.0-max- 480Pโ4K, 4โ30 s per clip, or
-1 - Precise camera moves and blocking, fewer continuity errors
- Multi-turn follow-ups via
conversation_id - Allowlist required
wand-vega-video-1.5-pro- 480Pโ4K, 4โ30 s per clip
- Supports
duration=-1(model decides) - Supports
asset://references - Allowlist required
wand-vega-video-1.5-lite- 480Pโ4K, 2โ30 s per clip
- Duration can go as low as 2 s
- No allowlist needed
- No
asset://, no-1
1.0-pro ยท 1.0-pro-fast ยท 1.0-pro-mini- 480Pโ4K, 4โ15 s per clip
- Standard, Fast, and Mini variants
- Supports
asset://references - Allowlist required
wand-vega-video-1.0-lite- 480Pโ4K, 4โ15 s per clip
- Default resolution 768P
- No allowlist needed
- No
asset://, no-1
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:
/v1/wand/vega-video-assets- Create, query, and delete materials
- Group and bulk-delete by
group_id - Get
asset://<id>for Pro references
/v1/wand/vega-video-liveness- Start verification, get the H5 face-check link
- Poll the result, get
group_id - Needed for
is_real_person=truematerials
Basic information โ
| Item | Value |
|---|---|
| Access path | Tokenhub API |
| Input | Text / first-and-last frame / reference image, video, audio |
| Generation mode | Asynchronous, typically 1โ3 minutes |
| Submit task | POST /v1/wand/vega-videos/tasks |
| Query result | GET /v1/wand/vega-videos/tasks/{id} |
| Result field | content.video_url, valid for 12 hours |
| Material reference | Pro only, asset://<id> โ see Material management |
Supported specs by version โ
| Version | model value | Resolution | Duration (s) | Allowlist |
|---|---|---|---|---|
| 1.0 Max | wand-vega-video-1.0-max | 480P / 720P / 1080P / 2K / 4K | 4โ30, or -1 | Required |
| 1.5 Pro | wand-vega-video-1.5-pro | 480P / 720P / 1080P / 2K / 4K | 4โ30, or -1 | Required |
| 1.5 Lite | wand-vega-video-1.5-lite | 480P / 720P / 1080P / 2K / 4K | 2โ30 | Not required |
| 1.0 Pro | wand-vega-video-1.0-pro | 480P / 720P / 1080P / 2K / 4K | 4โ15, or -1 | Required |
| 1.0 Pro Fast | wand-vega-video-1.0-pro-fast | 480P / 720P / 1080P / 2K / 4K | 4โ15, or -1 | Required |
| 1.0 Pro Mini | wand-vega-video-1.0-pro-mini | 480P / 720P / 1080P / 2K / 4K | 4โ15, or -1 | Required |
| 1.0 Lite | wand-vega-video-1.0-lite | 480P / 768P / 1080P / 2K / 4K | 4โ15 | Not 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.
| Step | Description |
|---|---|
| Enable the service | Register a Tencent Cloud account and enable TokenHub |
| Get an API Key | Create one in the TokenHub console โ see Get an API Key |
| Authentication | Request header Authorization: Bearer YOUR_API_KEY |
| Request tracing | Optionally 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:
- Submit the task:
POST /v1/wand/vega-videos/tasksreturnsHTTP 201with anidandstatus=queued. - Poll the result: call
GET /v1/wand/vega-videos/tasks/{id}every3โ5 secondsuntilstatusissucceededorfailed. On success, download the video fromcontent.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:
| Path | Applicable material | Call chain | Reference |
|---|---|---|---|
| โ General video generation | Materials without faces, or plain text / first-and-last-frame generation | Create task โ query result | Per-version references (cards above) |
| โก Non-real-person material | Non-real people, virtual humans, cartoon characters, etc. | Create material โ query material โ create task โ query result | Material management |
| โข Real-person material | Photographs of real people | Start liveness verification โ query verification โ create real-person material โ query material โ create task โ query result | Liveness 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.
{
"error": {"code": "<error code>", "message": "<error description>"},
"request_id": "<echo of the inbound X-Request-Id; omitted when the header is absent>"
}| HTTP status | error.code | Trigger and handling |
|---|---|---|
400 | invalid_request_error | Missing required field, wrong type, enum out of range, JSON parse failure. Check the value ranges in the per-version reference |
401 | Defined by the gateway | Authorization header missing, or API Key invalid / expired. Returned at the gateway layer, so the gateway defines the code |
403 | permission_denied | The AppId has not been granted the capability (including material-library access). Contact your WAND representative |
404 | not_found | Task or material ID does not exist, wrong path, or the material was deleted |
413 | request_too_large | Request body over 1MiB (POST routes), or upstream response body over 1MiB |
500 | internal_error | Internal service failure. If you already hold a task ID, query the existing task instead of re-submitting |
503 | service_unavailable | Service 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.