tencent cloud

LLM Service TokenHub

DocumentaçãoLLM Service TokenHubAPI Integration GuideVideo Generation ModelWAND Video Generation API Guide

WAND Video Generation API Guide

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-10-16 21:32:31
Traduzido por IA

Overview

Tencent Cloud WAND (Tencent Cloud Audio/Video AI) is Tencent Cloud's AI capability brand built for audio and video scenarios. Audio and video scenarios are complex and diverse, making it difficult for general-purpose AI to deliver results directly. Leveraging Tencent Cloud's years of audio/video technology expertise and extensive business practices, WAND deeply integrates multimodal large models with audio/video engineering experience to provide AI atomic capabilities validated in real-world scenarios. WAND-Vega-Video is a cost-effective multimodal video generation model that supports text-to-video, first/last-frame-to-video, and reference-to-video generation, balancing cost and quality.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
Enable postpaid billing for the corresponding model in Console - Online Inference - Vision Models.
Note:
In all examples below, YOUR_API_KEY must be replaced with your own API Key. The authentication method is the request header Authorization: Bearer YOUR_API_KEY.

Call Process

Video generation is a time-consuming task (typically 1 to 3 minutes), so the API uses an asynchronous call mode, which is divided into two steps:
1. Submit a task: Call POST /v1/wand/vega-videos/tasks, which returns an id and status=queued upon success.
2. Poll for results: Call GET /v1/wand/vega-videos/tasks/{id} with the id until the status is succeeded or failed. Upon success, obtain the video URL from content.video_url.

Model List

Model Name
Model (API Parameter)
Supported Capability
Video Duration (s)
Resolution Tier
WAND-Vega-Video-1.0-Lite
wand-vega-video-1.0-lite
Text-to-video / first-last frame generation / reference-based generation
4 ~ 15
768P,1080P,2K,4K

Video Generation

1. API Description

Submit a video generation task. The three generation modes (text-to-video, first/last-frame-to-video, and reference-to-video) share this API and are distinguished by the combination of type and role of elements in the content array.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model name. Value:
wand-vega-video-1.0-lite
content
Yes
array[object]
Multimodal input array. It must contain at least one type=text element (text prompts are required for generation). For details, see content array element parameters below.
resolution
No
string
Video resolution.
Lite values: 768P, 1080P, 2K, 4K
ratio
No
string
Aspect ratio.
Valid values: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive (default).
Here, adaptive indicates that the value is automatically determined by the model or input material.
duration
No
integer
Video duration in seconds.
Value: an integer from 4 to 15, default 5.
options
No
object
A collection of advanced or extended parameters. The entire object is optional. If it is not passed or is an empty object, it is equivalent to all fields being omitted. Each field can also be omitted individually.

Fields of the options Object

The options parameter carries the "Advanced / Extended" tier parameters.
Parameter Name
Required
Type
Description
options.return_last_frame
No
boolean
Whether to return the last frame image of the generated video. Value: true/false. Default: false. When set to true, if the model actually produces a last frame, the query API returns its temporary download URL in content.last_frame_url. If no last frame is produced, this field is absent.

Parameters of Elements in the content Array

content is a union-type array distinguished by type, and the fields of each element are mutually exclusive:
Parameter Name
Required
Type
Description
type
Yes
string
Element type. Values: text, image_url, video_url, audio_url.
text
Conditionally required
string
Text prompt. Required and cannot be an empty string when type=text. When multiple text elements exist, they are concatenated in array order to form the complete prompt.
image_url
Conditionally required
object
Image material. Required when type=image_url. Structure: {"url": "..."}, where url cannot be an empty string.
video_url
Conditionally required
object
Video material. Required when type=video_url. Structure: {"url": "..."}, where url cannot be an empty string.
audio_url
Conditionally required
object
Audio material. Required when type=audio_url. Structure: {"url": "..."}, where url cannot be an empty string.
role
Conditionally required
string
Material purpose. Required when type is image_url / video_url / audio_url (not used when type=text).
Values: first_frame, last_frame, reference_image, reference_video, reference_audio.
type=image_url: use first_frame for the first frame, last_frame for the last frame, and reference_image for the reference image;
type=video_url: fixed as reference_video;
type=audio_url: fixed as reference_audio.
The combination of type and role:
type
role
Actual Use
image_url
first_frame
First frame image
image_url
last_frame
Last frame image
image_url
reference_image
Reference image
video_url
reference_video (fixed)
Reference video
audio_url
reference_audio (fixed)
Reference audio
text
Not used
-

3. Sample Request for Text-to-Video Generation

Generate a video using only text prompts. The content array contains only one type=text element, and resolution, ratio, and duration can all be explicitly specified.
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-lite",
  "content": [
    {
      "type": "text",
      "text": "An orange kitten on the windowsill looks toward the camera, sunlight streams in from the side, and the camera slowly pushes in"
    }
  ],
  "resolution": "768P",
  "ratio": "16:9",
  "duration": 6
}'

4. Sample Request for First-Last-Frame-to-Video Generation

Generate a video using 1 to 2 images as the first frame / last frame, combined with text prompts. Pass elements with type=image_url and role set to first_frame / last_frame in content.
Note:
A maximum of 1 first frame (role=first_frame) and a maximum of 1 last frame (role=last_frame) are allowed.
At least one type=text element must be included.
If ratio is not specified, the aspect ratio is determined by the input image. You can also explicitly specify 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive.
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-lite",
  "content": [
    {
      "type": "text",
      "text": "The camera transitions naturally from the first frame to the last frame, maintaining continuous lighting and shadow"
    },
    {
      "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
}'

5. Sample Request for Reference-to-Video Generation

Generate a video using a combination of text + reference images / reference videos / reference audio. Pass elements with type=image_url / type=video_url / type=audio_url in content:
type=image_url: pass reference_image to role.
type=video_url: role is fixed as reference_video.
type=audio_url: role is fixed as reference_audio.
role is required for all three types above. If role is omitted or left empty, the request will be rejected.
Note:
At least one type=text element must be included.
It is recommended to include at least one reference image or reference video. Do not provide only audio.
It is recommended to use no more than 9 reference images, 3 reference videos, and 3 reference audio clips, with a total of no more than 12 assets.
File URLs do not currently support Base64 inline data. Support for this feature is in progress.
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-lite",
  "content": [
    {
      "type": "text",
      "text": "The character in the reference image moves naturally within the scene of the reference video, with the background music synchronized to the visual rhythm"
    },
    {
      "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": "768P",
  "ratio": "16:9",
  "duration": 10
}'

6. Output Parameters

Note:
A successful submission is indicated by HTTP status code 201 + a returned id. The response body does not contain an error information block.
The submission API does not provide request-level idempotency: each submission generates a new task ID. Manage retries on your own using a business-side request identifier to avoid duplicate generation and billing.
Parameter Name
Type
Description
id
string
Task ID, used for polling to query task status.
model
string
Value of model echoed upon submission.
status
string
Task status. Upon successful submission, it is always queued.

7. Sample Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "1300000000-video-68b7c1d4a1f2e3d4c5b6a79808192a3b4c5d6e7f8-0000",
  "model": "wand-vega-video-1.0-lite",
  "status": "queued"
}

Querying the Task Result

1. API Description

Common task query endpoint for all generation modes: After submitting a task and receiving an id, poll the task status through this API. Upon success, obtain the video URL from content.video_url.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks/{id}

2. Input Parameters

Parameter Name
Required
Type
Description
id
Yes
string
Task ID (path parameter), which is the id returned when the task is submitted.

3. Request Example

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vega-videos/tasks/<Fid>' \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer YOUR_API_KEY'

4. Output Parameters

Parameter Name
Type
Description
id
string
Task ID.
model
string
Echoes the model value at submission, not the actual model used for video generation.
status
string
Task status. Values: queued (pending scheduling), running (generating), succeeded (successful), failed (failed).
content
object
Content of the generated task result, returned only when status=succeeded.
content.video_url
string
Download URL of the generated video. It is a temporary URL valid for 12 hours. Download and store it promptly.
content.last_frame_url
string
URL of the last frame image of the generated video. Returned only when options.return_last_frame=true.
error
object
Task failure information, returned only when status=failed.
error.code
string
Task-level error code. Values: InternalError, TaskTimeout, and others.
error.message
string
Description of the failure reason, which helps locate the issue.

5. Response Example

{
  "id": "1300000000-video-68b7c1d4a1f2e3d4c5b6a79808192a3b4c5d6e7f8-0000",
  "model": "wand-vega-video-1.0-lite",
  "status": "succeeded",
  "content": {
    "video_url": "https://aigc-video.example.com/xxx/result.mp4"
  }
}

Appendix

Unified Error Codes

HTTP Status Code
error.code
Meaning
Recommended Solution
401
Defined by the gateway.
Authentication failed: The Authorization header is missing or the API Key is invalid/expired. This error is returned at the gateway layer, and the error code is defined by the gateway.
Check whether the Authorization: Bearer <API Key> is correct and within its validity period.
400
invalid_request_error
Invalid request parameters (missing required fields, incorrect types, out-of-range enum values, JSON parsing failures, and so on).
Check the valid value range of each parameter in this document and retry.
404
not_found
The resource does not exist (the task ID does not exist, the path is incorrect, and so on).
Confirm whether the path and task ID are correct.
500
internal_error
Internal service error or processing timeout.
Retry. If failures persist, contact technical support.
503
service_unavailable
The service is overloaded and temporarily unavailable.
Retry with backoff.

FAQs

1. Will an Unsupported resolution Be Degraded?

No. A resolution that exceeds the current model tier will be directly rejected with a 400 invalid_request_error during the submission phase (for example, passing 720P to Lite).

2. Will the Generated Video Link Expire?

The generated result is a temporary address that expires in 12 hours. Download and save it to your own storage promptly after the task succeeds.

3. What Should I Do if the Task Remains in queued Status After Successful Submission?

Tasks that time out in the queue will be marked as failed and return error.code = TaskTimeout. If a task remains in queued status for a long time, retry later and contact technical support with the task id.

Anterior: Video Generation Model Invocation OverviewPróximo: Vidu Video Generation API Guide

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation