PixVerse โ
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-videoAuthentication: Tokenhub API Key / Bearer
PixVerse is a video generation model that generates video from text, images, first / last frames, or reference images. After submitting a task, query the result by task ID.
Basic Information โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Guardrail bypass support | Not supported |
Supported Specifications by Version โ
| Version | Resolution | Aspect ratio | Duration |
|---|---|---|---|
pixverse-video-v6.0 | 360p / 540p / 720p / 1080p | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9 | 1 ~ 15 seconds |
pixverse-video-c1 | 360p / 540p / 720p / 1080p | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9 | 1 ~ 15 seconds |
Input Modes โ
| Version | Input |
|---|---|
pixverse-video-v6.0 | Text-to-video / Image-to-video / First & last frame / Reference-based generation |
pixverse-video-c1 | Text-to-video / Image-to-video / First & last frame / Reference-based generation |
Call Procedure โ
Video generation is a long-running task (typically 1~5 minutes). API uses an asynchronous call pattern, split into the following two steps.
- Submit the task: Call the feature API (text-to-video / image-to-video / first & last frame-to-video / reference-to-video). On success,
Resp.video_id(task ID) is returned. - Poll for the result: Call the task result query API with
video_id. We recommend polling every3~5 secondsuntil it becomesResp.status = 1(generation succeeded), then retrieving the resulting video fromResp.url.
Note: Once a task has been created successfully, do not submit it again โ poll for the result instead. Common response format: ErrCode (0 means success), ErrMsg (message), Resp (data object).
Text-to-Video โ
API Description โ
Generates video from a text prompt alone, with support for camera movement, audio, and the multi-shot toggle.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| prompt | Required | string | Text prompt describing the desired video content. Value range: โค 5000 characters. |
| model | Required | string | Model version. Value range: pixverse-video-v6.0, pixverse-video-c1 |
| duration | Required | integer | Video duration in seconds. Value range: an integer in 1~15. Default: 5. |
| quality | Required | string | Video clarity. Value range: 360p / 540p / 720p / 1080p. |
| aspect_ratio | Optional | string | Aspect ratio. Value range: 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9. Default: 16:9. |
| camera_movement | Optional | string | Camera movement (for example zoom_in, use as needed). |
| seed | Optional | integer | Random seed. Value range: 0~2147483647. If omitted or set to 0, a random number is used. |
| generate_audio_switch | Optional | boolean | Audio switch. true = with sound (automatically generates matching background music or sound effects), false = muted. Default: false. |
| generate_multi_clip_switch | Optional | boolean | Multi-shot switch, supported on pixverse-video-v6.0 only. true = multi-shot (the system splits shots intelligently), false = single shot. Default: false. |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "pixverse-video-v6.0",
"prompt": "An orange kitten on the windowsill looks toward the camera",
"duration": 5,
"quality": "360p",
"aspect_ratio": "16:9"
}'Note: To call the corresponding model, replace model in the example with pixverse-video-c1.
Response Parameters โ
| Field | Type | Description |
|---|---|---|
| ErrCode | integer | Error code; 0 indicates success. |
| ErrMsg | string | Error or informational message. |
| Resp | object | Response data object. |
| Resp.video_id | string | Task ID used for polling the task status. |
| request_id | string | Unique request identifier used for troubleshooting. |
Response Example โ
{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"video_id": "4-WandVideo-4ba31a7d508249b787fa0b0c62a6a399"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}Error Codes โ
When a request fails, ErrCode is not 0. For the specific cause, see ErrMsg. Once the task has been submitted successfully, you can retrieve the task status of the generation stage through the "Task Result Query" API.
| status | Description | Recommended handling |
|---|---|---|
1 | Generation succeeded | Retrieve the resulting video from Resp.url. |
5 | Generating | Poll once every 3~5 seconds until status=1. |
6 | Deleted | The task result has been deleted. Start the task again. |
7 | Content moderation failed | Check whether the prompt/image contains prohibited content, revise it, and retry. |
8 | Generation failed | A server-side generation error occurred. Retry the request. If it keeps failing, contact the technical support team and provide the task ID. |
Image-to-Video โ
API Description โ
Uses an image as the first frame to generate a video with motion. The image is passed directly as a publicly accessible URL, and the aspect ratio of the output video follows that of the input image. Supports negative prompts, camera movement, audio, and the multi-shot toggle.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/image-to-video
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| img_id | Required | string | Image address, which can be a publicly accessible image URL or base64 image data. |
| img_ids | Optional | array[string] | Array of image URLs reserved for multi-image templates (for example ["url1", "url2"]). |
| prompt | Required | string | Text prompt. Value range: โค 5000 characters. |
| model | Required | string | Model version. Value range: pixverse-video-v6.0, pixverse-video-c1 |
| duration | Required | integer | Video duration in seconds. Value range: an integer in 1~15. Default: 5. |
| quality | Required | string | Video clarity. Value range: 360p / 540p / 720p / 1080p. |
| camera_movement | Optional | string | Camera movement (for example zoom_in, use as needed). |
| seed | Optional | integer | Random seed. Value range: 0~2147483647. If omitted or set to 0, a random number is used. |
| generate_audio_switch | Optional | boolean | Audio switch. true = with sound, false = muted. Default: false. |
| generate_multi_clip_switch | Optional | boolean | Multi-shot switch, supported on pixverse-video-v6.0 only. true = multi-shot, false = single shot. Default: false. |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/image-to-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "pixverse-video-v6.0",
"prompt": "Make the subject in the image turn its head naturally",
"img_id": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png",
"duration": 5,
"quality": "360p"
}'Note: To call the corresponding model, replace model in the example with pixverse-video-c1.
Response Parameters โ
| Field | Type | Description |
|---|---|---|
| ErrCode | integer | Error code; 0 indicates success. |
| ErrMsg | string | Error or informational message. |
| Resp | object | Response data object. |
| Resp.video_id | string | Video ID of the generation task, used for polling the task status. |
| request_id | string | Unique request identifier used for troubleshooting. |
Response Example โ
{
"ErrCode": 0,
"ErrMsg": "success",
"Resp": {
"video_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}Error Codes โ
When a request fails, ErrCode is not 0. For the specific cause, see ErrMsg. Once the task has been submitted successfully, you can retrieve the task status of the generation stage through the "Task Result Query" API.
| status | Description | Recommended handling |
|---|---|---|
1 | Generation succeeded | Retrieve the resulting video from Resp.url. |
5 | Generating | Poll once every 3~5 seconds until status=1. |
6 | Deleted | The task result has been deleted. Start the task again. |
7 | Content moderation failed | Check whether the prompt/image contains prohibited content, revise it, and retry. |
8 | Generation failed | A server-side generation error occurred. Retry the request. If it keeps failing, contact the technical support team and provide the task ID. |
First & Last Frame-to-Video โ
Start End To Video โ
Designates two images as the first and last frames (publicly accessible URLs) to generate a video that transitions naturally between the two frames. The aspect ratio of the output video follows that of the input images.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/start-end-to-video
Note: For the best transition effect, we recommend keeping the aspect ratio of the first and last frame images identical.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| prompt | Required | string | Text prompt describing the transition content. Value range: โค 5000 characters. Example: "transition naturally from the first frame to the last frame" |
| first_frame_img | Required | string | First frame image address, which can be a publicly accessible image URL or base64 image data. |
| last_frame_img | Required | string | Last frame image address, which can be a publicly accessible image URL or base64 image data. |
| model | Required | string | Model version. Value range: pixverse-video-v6.0, pixverse-video-c1 |
| duration | Required | integer | Video duration in seconds. Value range: an integer in 1~15. Default: 5. |
| quality | Required | string | Video clarity. Value range: 360p / 540p / 720p / 1080p. |
| seed | Optional | integer | Random seed. Value range: 0~2147483647. If omitted or set to 0, a random number is used. |
| generate_audio_switch | Optional | boolean | Audio switch. true = with sound, false = muted. Default: false. |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/start-end-to-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "pixverse-video-v6.0",
"prompt": "Transition naturally from the first frame to the last frame",
"first_frame_img": "https://example.com/start.jpg",
"last_frame_img": "https://example.com/end.jpg",
"duration": 5,
"quality": "360p"
}'Note: To call the corresponding model, replace model in the example with pixverse-video-c1.
Response Parameters โ
| Field | Type | Description |
|---|---|---|
| ErrCode | integer | Error code; 0 indicates success. |
| ErrMsg | string | Error or informational message. |
| Resp | object | Response data object. |
| Resp.video_id | string | Task ID used for polling the task status. |
| request_id | string | Unique request identifier used for troubleshooting. |
Response Example โ
{
"ErrCode": 0,
"ErrMsg": "success",
"Resp": {
"video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}Error Codes โ
When a request fails, ErrCode is not 0. For the specific cause, see ErrMsg. Once the task has been submitted successfully, you can retrieve the task status of the generation stage through the "Task Result Query" API.
| status | Description | Recommended handling |
|---|---|---|
1 | Generation succeeded | Retrieve the resulting video from Resp.url. |
5 | Generating | Poll once every 3~5 seconds until status=1. |
6 | Deleted | The task result has been deleted. Start the task again. |
7 | Content moderation failed | Check whether the prompt/image contains prohibited content, revise it, and retry. |
8 | Generation failed | A server-side generation error occurred. Retry the request. If it keeps failing, contact the technical support team and provide the task ID. |
Reference-to-Video Generation โ
API Description โ
Combines a set of reference images (reference subject / background) with a prompt to generate a video that keeps the reference subject consistent. Reference images are passed directly as publicly accessible URLs, and you can use @ref_name in the prompt to refer to a specific reference image.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/reference-to-video
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| image_references | Required | array[object] | Array of reference images. Supports up to 7 entries. For subfields, see the table below. |
| prompt | Required | string | Text prompt. Value range: 5000 characters or fewer. Use @ref_name to reference an image (put a space after @). Example: "@dog plays in the @room". |
| model | Required | string | Model version. Value range: pixverse-video-v6.0, pixverse-video-c1 |
| duration | Required | integer | Video duration in seconds. Value range: an integer in 1~15. Default: 5. |
| quality | Required | string | Video clarity. Value range: 360p / 540p / 720p / 1080p. |
| aspect_ratio | Optional | string | Aspect ratio. Value range: 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9. Default: 16:9. |
| generate_audio_switch | Optional | boolean | Audio switch. true = with sound, false = muted. Default: false. |
| seed | Optional | integer | Random seed. Value range: 0~2147483647. |
Subfields of the image_references array elements:
| Parameter | Required | Type | Description |
|---|---|---|---|
| img_id | Required | string | Reference image address, which can be a publicly accessible image URL or base64 image data. |
| type | Optional | string | Reference image type. Values: subject/background. |
| ref_name | Optional | string | Reference image name, which must be 30 characters or fewer. Used to reference it as @ref_name in the prompt. |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/reference-to-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "pixverse-video-v6.0",
"prompt": "Make the subject in the reference image wave naturally",
"image_references": [
{
"img_id": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png",
"type": "subject"
}
],
"duration": 5,
"quality": "360p",
"aspect_ratio": "16:9"
}'Note: To call the corresponding model, replace model in the example with pixverse-video-c1.
Response Parameters โ
| Field | Type | Description |
|---|---|---|
| ErrCode | integer | Error code; 0 indicates success. |
| ErrMsg | string | Error or informational message. |
| Resp | object | Response data object. |
| Resp.video_id | string | Task ID used for polling the task status. |
| request_id | string | Unique request identifier used for troubleshooting. |
Response Example โ
{
"ErrCode": 0,
"ErrMsg": "success",
"Resp": {
"video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}Error Codes โ
When a request fails, ErrCode is not 0. For the specific cause, see ErrMsg. Once the task has been submitted successfully, you can retrieve the task status of the generation stage through the "Task Result Query" API.
| status | Description | Recommended handling |
|---|---|---|
1 | Generation succeeded | Retrieve the resulting video from Resp.url. |
5 | Generating | Poll once every 3~5 seconds until status=1. |
6 | Deleted | The task result has been deleted. Start the task again. |
7 | Content moderation failed | Check whether the prompt/image contains prohibited content, revise it, and retry. |
8 | Generation failed | A server-side generation error occurred. Retry the request. If it keeps failing, contact the technical support team and provide the task ID. |
Task Result Query โ
API Description โ
The shared task query API used by all four features API, for polling generation results.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/tasks/{task_id}
Note: The {task_id} in the path is the Resp.video_id returned when the task was submitted. Video generation takes roughly a few minutes, so we recommend polling every 3~5 seconds.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | Task ID (path parameter), that is, the Resp.video_id returned when the task was submitted. |
Request Example โ
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| ErrCode | integer | Error code; 0 indicates success. |
| ErrMsg | string | Error or informational message |
| Resp | object | Response data object (task details) |
| Resp.id | string | Video ID (video_id) |
| Resp.status | integer | Video status: 1 succeeded / 5 generating / 6 deleted / 7 moderation failed / 8 generation failed |
| Resp.url | string | URL of the video result after generation succeeds |
| Resp.prompt | string | Prompt used for this generation |
| Resp.negative_prompt | string | Negative prompt |
| Resp.seed | integer | Random seed |
| Resp.style | string | Style |
| Resp.resolution_ratio | integer | Video clarity |
| Resp.outputWidth | integer | Video width |
| Resp.outputHeight | integer | Video height |
| Resp.size | integer | Video file size |
| Resp.create_time | string | Task creation time. |
| Resp.modify_time | string | Task update time. |
| tokenhub_usage | object | Usage |
| tokenhub_usage.total_tokens | integer | Number of tokens used |
| request_id | string | Unique request identifier used for troubleshooting. |
Response Example โ
Generation succeeded:
{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
"status": 1,
"url": "https://example.com/output-video.mp4?q-sign=xxxxxx",
"prompt": "An orange kitten on the windowsill looks toward the camera",
"negative_prompt": "",
"seed": 0,
"style": "",
"resolution_ratio": 720,
"outputWidth": 1280,
"outputHeight": 720,
"size": 0,
"create_time": "2026-07-29 15:41:31",
"modify_time": "2026-07-29 15:42:10"
},
"tokenhub_usage": {
"total_tokens": 102655
},
"request_id": "2524bc44-5c6f-4114-9b94-6c57eb85f54a-query-1785393236"
}6. Status Codes โ
| status | Description | Recommended handling |
|---|---|---|
1 | Generation succeeded | Retrieve the resulting video from Resp.url. |
5 | Generating | Poll once every 3~5 seconds until status=1. |
6 | Deleted | The task result has been deleted. Start the task again. |
7 | Content moderation failed | Check whether the prompt/image contains prohibited content, revise it, and retry. |
8 | Generation failed | A server-side generation error occurred. Retry the request. If it keeps failing, contact the technical support team and provide the task ID. |
Appendix: Quick Reference for Common Parameter Limits โ
| Parameter | Description |
|---|---|
| duration | An integer in 1~15 (1080p also supports up to 15 seconds). |
| aspect_ratio | Supported only for text-to-video and reference-to-video. Values: 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9, default: 16:9. Image-to-video and first/last frame-to-video do not support this parameter; the output aspect ratio follows that of the input image. |
| generate_multi_clip_switch | Supported only for text-to-video and image-to-video on pixverse-video-v6.0; not supported for first/last frame and reference-to-video. |
Frequently Asked Questions โ
1. Which of the two models should I choose? โ
- For general scenarios, or when multi-shot intelligent storyboarding is needed:
pixverse-video-v6.0. - For dynamic scenes such as combat, magic effects, and high-speed motion:
pixverse-video-c1.
2. How do I pass images to image-to-video, first/last frame, and reference-to-video API? โ
You can pass a publicly accessible image URL directly. img_id (image-to-video), first_frame_img / last_frame_img (first and last frame), and image_references.img_id (reference-to-video) can all accept an image URL string without calling the upload API first.
3. Do the generated video links expire? โ
URLs do expire. Download the video file from Resp.url immediately after the task succeeds. The validity period does not exceed 12 hours, so download and save it as soon as possible.