tencent cloud

LLM Service TokenHub

DokumentasiLLM Service TokenHubAPI Integration GuideVideo Generation ModelPixVerse API Guide

PixVerse API Guide

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-10 22:08:17
Diterjemahkan oleh AI

Overview

PixVerse (Aishi Technology) is a video generation model series designed for short video creation scenarios. It supports four capabilities: text-to-video, image-to-video, first-and-last-frame-to-video, and reference-to-video, and features multi-resolution, multi-aspect-ratio, camera movement control, audio generation, and multi-shot storyboarding.
This document describes how to call two PixVerse models through TokenHub: pixverse-video-v6.0 and pixverse-video-c1.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
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 5 minutes). The API uses an asynchronous call mode, which is divided into two steps:
1. Submit a task: Call the capability API (text-to-video/image-to-video/first-and-last-frame-to-video/reference-to-video), which returns Resp.video_id (task ID) upon success.
2. Poll for results: Call the query task result API with the video_id. It is recommended to poll every 3 to 5 seconds until Resp.status = 1 (generation succeeded), and then obtain the result video from Resp.url.
Note:
Do not resubmit the task after it is created successfully. Obtain the result by polling. Common response format: ErrCode (0 indicates success), ErrMsg (message), and Resp (data object).

Model List

Model Name
model Parameter Value
Supported Capability
Video Duration (s)
Resolution Tier
Aspect Ratio (Text-to-Video/Reference-to-Video)
Selection Recommendations
PixVerse-Video-v6
pixverse-video-v6.0
Text-to-video / image-to-video / first-last frame / reference-based generation
1 ~ 15
360p / 540p / 720p / 1080p
16:9,4:3,1:1,3:4,9:16,2:3,3:2,21:9
Recommended for general scenarios, supports multi-shot intelligent storyboarding.
PixVerse-Video-c1
pixverse-video-c1
Text-to-video / image-to-video / first-last frame / reference-based generation
1 ~ 15
360p / 540p / 720p / 1080p
16:9,4:3,1:1,3:4,9:16,2:3,3:2,21:9
Recommended for dynamic scenes such as combat, spell effects, and high-speed motion; supports automatic generation of structured storyboards from prompts.
Note:
The Aspect Ratio column lists the supported value range for text-to-video and reference-to-video. For image-to-video and first-and-last-frame-to-video, the output aspect ratio follows the input image ratio by default.

Text-to-Video

1. API Description

Generate videos using only text prompts, with support for camera movement, audio, and multi-shot toggles.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video

2. Input Parameters

Parameter Name
Required
Type
Description
prompt
Yes
string
Text prompt that describes the desired video content. Value range: ≤ 5000 characters.
model
Yes
string
Model version. Value range: pixverse-video-v6.0, pixverse-video-c1
duration
Yes
integer
Video duration in seconds. Value range: an integer from 1 to 15. Default value: 5.
quality
Yes
string
Video clarity. Value range: 360p / 540p / 720p / 1080p.
aspect_ratio
No
string
Aspect ratio. Value range: 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9. Default value: 16:9.
camera_movement
No
string
Camera movement, such as zoom_in (used as needed).
seed
No
integer
Random seed. Value range: 0 to 2147483647. If not specified or set to 0, a random number is used.
generate_audio_switch
No
boolean
Audio switch. true=with sound (automatically generates matching background music or sound effects), false=muted. Default value: false.
generate_multi_clip_switch
No
boolean
Multi-shot switch, only pixverse-video-v6.0 supports. true=multi-shot (system intelligently splits shots), false=single shot. Default value: false.

3. Sample Request

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:
Replace model in the example with pixverse-video-c1 to call the corresponding model.

4. Output Parameters

Field
Type
Description
ErrCode
integer
Error code; 0 indicates success.
ErrMsg
string
Error or prompt information.
Resp
object
Response data object.
Resp.video_id
string
Task ID, used for polling task status.
request_id
string
Unique request identifier used for troubleshooting.

5. Sample Response

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": "4-WandVideo-4ba31a7d508249b787fa0b0c62a6a399"
  },
  "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

6. Error Codes

When a request fails, ErrCode is not 0. See ErrMsg for the specific reason. After a task is submitted successfully, the task status during the generation phase can be obtained through the "Query Task Result" API:
status
Description
Handling Recommendation
1
Generation succeeded
Obtain the result video from Resp.url.
5
Generating
Poll once every 3 to 5 seconds until status=1.
6
Deleted
The task result has been deleted. Initiate the task again.
7
Content moderation failed
Check whether the prompt/image contains prohibited content, make modifications, and retry.
8
Generation failed
A server-side generation error occurs. Retry the request. If the failure persists, contact technical support and provide the task ID.

Image-to-Video

1. API Description

Generate a dynamic video using an image as the first frame. Pass the image directly as a publicly accessible URL, and the output video aspect ratio follows the input image ratio. Negative prompts, camera movement, audio, and multi-shot toggles are supported.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/image-to-video

2. Input Parameters

Parameter Name
Required
Type
Description
img_id
Yes
string
Image address, which can be a publicly accessible image URL or base64 image data.
img_ids
No
array[string]
Image URL array dedicated to multi-image templates, such as ["url1", "url2"].
prompt
Yes
string
Text prompt. Value range: ≤ 5000 characters.
model
Yes
string
Model version. Value range: pixverse-video-v6.0, pixverse-video-c1
duration
Yes
integer
Video duration in seconds. Value range: an integer from 1 to 15. Default value: 5.
quality
Yes
string
Video clarity. Value range: 360p / 540p / 720p / 1080p.
camera_movement
No
string
Camera movement, such as zoom_in (used as needed).
seed
No
integer
Random seed. Value range: 0 to 2147483647. If not specified or set to 0, a random number is used.
generate_audio_switch
No
boolean
Audio switch. true=with sound, false=muted. Default value: false.
generate_multi_clip_switch
No
boolean
Multi-shot switch, only pixverse-video-v6.0 supports. true=multi-shot, false=single shot. Default value: false.

3. Sample Request

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://example.com/input.jpg",
  "duration": 5,
  "quality": "360p"
}'
Note:
Replace model in the example with pixverse-video-c1 to call the corresponding model.

4. Output Parameters

Field
Type
Description
ErrCode
integer
Error code; 0 indicates success.
ErrMsg
string
Error or prompt information.
Resp
object
Response data object.
Resp.video_id
string
Video ID of the generated task, used for polling to query task status.
request_id
string
Unique request identifier used for troubleshooting.

5. Sample Response

{
    "ErrCode": 0,
    "ErrMsg": "success",
    "Resp": {
        "video_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
    },
    "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

6. Error Codes

When a request fails, ErrCode is not 0. See ErrMsg for the specific reason. After a task is submitted successfully, the task status during the generation phase can be obtained through the "Query Task Result" API:
status
Description
Handling Recommendation
1
Generation succeeded
Obtain the result video from Resp.url.
5
Generating
Poll once every 3 to 5 seconds until status=1.
6
Deleted
The task result has been deleted. Initiate the task again.
7
Content moderation failed
Check whether the prompt/image contains prohibited content, make modifications, and retry.
8
Generation failed
A server-side generation error occurs. Retry the request. If the failure persists, contact technical support and provide the task ID.

First and Last Frame to Video

1. API Description

Given two images as the first and last frames (publicly accessible URLs), generate a video that transitions smoothly between them. The output video aspect ratio follows the input image ratio.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/start-end-to-video
Note:
It is recommended that the first and last frame images maintain the same aspect ratio to achieve the best transition effect.

2. Input Parameters

Parameter Name
Required
Type
Description
prompt
Yes
string
Text prompt that describes the transition content. Value range: ≤ 5000 characters. Example: "Naturally transition from the first frame to the last frame"
first_frame_img
Yes
string
First frame image address, which can be a publicly accessible image URL or base64 image data.
last_frame_img
Yes
string
Last frame image address, which can be a publicly accessible image URL or base64 image data.
model
Yes
string
Model version. Value range: pixverse-video-v6.0, pixverse-video-c1
duration
Yes
integer
Video duration in seconds. Value range: an integer from 1 to 15. Default value: 5.
quality
Yes
string
Video clarity. Value range: 360p / 540p / 720p / 1080p.
seed
No
integer
Random seed. Value range: 0 to 2147483647. If not specified or set to 0, a random number is used.
generate_audio_switch
No
boolean
Audio switch. true=with sound, false=muted. Default value: false.

3. Sample Request

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:
Replace model in the example with pixverse-video-c1 to call the corresponding model.

4. Output Parameters

Field
Type
Description
ErrCode
integer
Error code; 0 indicates success.
ErrMsg
string
Error or prompt information.
Resp
object
Response data object.
Resp.video_id
string
Task ID, used for polling task status.
request_id
string
Unique request identifier used for troubleshooting.

5. Sample Response

{
    "ErrCode": 0,
    "ErrMsg": "success",
    "Resp": {
        "video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
    },
    "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

6. Error Codes

When a request fails, ErrCode is not 0. See ErrMsg for the specific reason. After a task is submitted successfully, the task status during the generation phase can be obtained through the "Query Task Result" API:
status
Description
Handling Recommendation
1
Generation succeeded
Obtain the result video from Resp.url.
5
Generating
Poll once every 3 to 5 seconds until status=1.
6
Deleted
The task result has been deleted. Initiate the task again.
7
Content moderation failed
Check whether the prompt/image contains prohibited content, make modifications, and retry.
8
Generation failed
A server-side generation error occurs. Retry the request. If the failure persists, contact technical support and provide the task ID.

Reference to Video Generation

1. API Description

Generate a video with consistent subjects by combining a set of reference images (subjects/backgrounds) with a prompt. The reference images are directly passed in 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

2. Input Parameters

Parameter Name
Required
Type
Description
image_references
Yes
array[object]
Array of reference images. Supports up to 7 items. See the following table for subfields.
prompt
Yes
string
Text prompt. Value range: no more than 5000 characters. Use @ref_name to reference an image (with a space after @), for example, "@dog plays at @room".
model
Yes
string
Model version. Value range: pixverse-video-v6.0, pixverse-video-c1
duration
Yes
integer
Video duration in seconds. Value range: an integer from 1 to 15. Default value: 5.
quality
Yes
string
Video clarity. Value range: 360p / 540p / 720p / 1080p.
aspect_ratio
No
string
Aspect ratio. Value range: 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9. Default value: 16:9.
generate_audio_switch
No
boolean
Audio switch. true=with sound, false=muted. Default value: false.
seed
No
integer
Random seed. Value range: 0 to 2147483647.
Subfields of image_references array elements:
Parameter Name
Required
Type
Description
img_id
Yes
string
Reference image address, which can be a publicly accessible image URL or base64 image data.
type
No
string
Reference image type. Values: subject/background.
ref_name
No
string
Reference image name, no more than 30 characters; used to reference it in the prompt with @ref_name.

3. Sample Request

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://example.com/input.png",
      "type": "subject"
    }
  ],
  "duration": 5,
  "quality": "360p",
  "aspect_ratio": "16:9"
}'
Note:
Replace model in the example with pixverse-video-c1 to call the corresponding model.

4. Output Parameters

Field
Type
Description
ErrCode
integer
Error code; 0 indicates success.
ErrMsg
string
Error or prompt information.
Resp
object
Response data object.
Resp.video_id
string
Task ID, used for polling task status.
request_id
string
Unique request identifier used for troubleshooting.

5. Sample Response

{
    "ErrCode": 0,
    "ErrMsg": "success",
    "Resp": {
        "video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
    },
    "request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}

6. Error Codes

When a request fails, ErrCode is not 0. See ErrMsg for the specific reason. After a task is submitted successfully, the task status during the generation phase can be obtained through the "Query Task Result" API:
status
Description
Handling Recommendation
1
Generation succeeded
Obtain the result video from Resp.url.
5
Generating
Poll once every 3 to 5 seconds until status=1.
6
Deleted
The task result has been deleted. Initiate the task again.
7
Content moderation failed
Check whether the prompt/image contains prohibited content, make modifications, and retry.
8
Generation failed
A server-side generation error occurs. Retry the request. If the failure persists, contact technical support and provide the task ID.

Querying the Task Result

1. API Description

A shared task query API for the four capability APIs, used to poll for generated 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 (represented by YOUR_TASK_ID in the example). Video generation takes approximately several minutes, so polling every 3 to 5 seconds is recommended.

2. Input Parameters

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

3. Sample Request

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/tasks/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'

4. Output Parameters

Field
Type
Description
ErrCode
integer
Error code; 0 indicates success.
ErrMsg
string
Error or prompt information
Resp
object
Response data object (task details)
Resp.id
string
Video ID (video_id)
Resp.status
integer
Video status: 1 success / 5 generating / 6 deleted / 7 review failed / 8 generation failed
Resp.url
string
URL of the video result after successful generation
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 consumption
tokenhub_usage.total_tokens
integer
Number of consumed tokens
request_id
string
Unique request identifier used for troubleshooting.

5. Sample Response

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
Handling Recommendation
1
Generation succeeded
Obtain the result video from Resp.url.
5
Generating
Poll once every 3 to 5 seconds until status=1.
6
Deleted
The task result has been deleted. Initiate the task again.
7
Content moderation failed
Check whether the prompt/image contains prohibited content, make modifications, and retry.
8
Generation failed
A server-side generation error occurs. Retry the request. If the failure persists, contact technical support and provide the task ID.

Appendix: Quick Reference for General Parameter Limits

Parameter
Description
duration
An integer from 1 to 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 value: 16:9. Image-to-video and first-last-frame-to-video do not support this parameter, and the output aspect ratio follows the input image ratio.
generate_multi_clip_switch
Supported only for text-to-video and image-to-video of pixverse-video-v6.0; not supported for first-last-frame and reference-to-video.

FAQs

1. How to Choose Between the Two Models?

For general scenarios or when multi-shot intelligent storyboarding is required: pixverse-video-v6.0.
For dynamic scenes such as combat, spell effects, and high-speed motion: pixverse-video-c1.

2. How to Pass Images in Image-to-Video, First/Last Frame, and Reference-to-Video APIs?

You can directly pass publicly accessible image URLs: img_id (image-to-video), first_frame_img / last_frame_img (first and last frames), and image_references[].img_id (reference-to-video) all accept image URL strings without requiring a prior call to the upload API.

3. Do Generated Video Links Expire?

The URL will expire. Download the video file from Resp.url promptly after the task succeeds. The validity period does not exceed 12 hours, so download and save it as soon as possible.

Topik sebelumnya: Video Generation Model Invocation OverviewTopik selanjutnya: Kling API Guide

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation