Skip to content

PixVerse โ€‹

Updated

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 โ€‹

ItemValue
Call pathTokenhub API
Guardrail bypass supportNot supported

Supported Specifications by Version โ€‹

VersionResolutionAspect ratioDuration
pixverse-video-v6.0360p / 540p / 720p / 1080p16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:91 ~ 15 seconds
pixverse-video-c1360p / 540p / 720p / 1080p16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:91 ~ 15 seconds

Input Modes โ€‹

VersionInput
pixverse-video-v6.0Text-to-video / Image-to-video / First & last frame / Reference-based generation
pixverse-video-c1Text-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.

  1. 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.
  2. Poll for the result: Call the task result query API with video_id. We recommend polling every 3~5 seconds until it becomes Resp.status = 1 (generation succeeded), then retrieving the resulting video from Resp.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 โ€‹

ParameterRequiredTypeDescription
promptRequiredstringText prompt describing the desired video content. Value range: โ‰ค 5000 characters.
modelRequiredstringModel version. Value range: pixverse-video-v6.0, pixverse-video-c1
durationRequiredintegerVideo duration in seconds. Value range: an integer in 1~15. Default: 5.
qualityRequiredstringVideo clarity. Value range: 360p / 540p / 720p / 1080p.
aspect_ratioOptionalstringAspect ratio. Value range: 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9. Default: 16:9.
camera_movementOptionalstringCamera movement (for example zoom_in, use as needed).
seedOptionalintegerRandom seed. Value range: 0~2147483647. If omitted or set to 0, a random number is used.
generate_audio_switchOptionalbooleanAudio switch. true = with sound (automatically generates matching background music or sound effects), false = muted. Default: false.
generate_multi_clip_switchOptionalbooleanMulti-shot switch, supported on pixverse-video-v6.0 only. true = multi-shot (the system splits shots intelligently), false = single shot. Default: false.

Request Example โ€‹

bash
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 โ€‹

FieldTypeDescription
ErrCodeintegerError code; 0 indicates success.
ErrMsgstringError or informational message.
RespobjectResponse data object.
Resp.video_idstringTask ID used for polling the task status.
request_idstringUnique request identifier used for troubleshooting.

Response Example โ€‹

json
{
  "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.

statusDescriptionRecommended handling
1Generation succeededRetrieve the resulting video from Resp.url.
5GeneratingPoll once every 3~5 seconds until status=1.
6DeletedThe task result has been deleted. Start the task again.
7Content moderation failedCheck whether the prompt/image contains prohibited content, revise it, and retry.
8Generation failedA 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 โ€‹

ParameterRequiredTypeDescription
img_idRequiredstringImage address, which can be a publicly accessible image URL or base64 image data.
img_idsOptionalarray[string]Array of image URLs reserved for multi-image templates (for example ["url1", "url2"]).
promptRequiredstringText prompt. Value range: โ‰ค 5000 characters.
modelRequiredstringModel version. Value range: pixverse-video-v6.0, pixverse-video-c1
durationRequiredintegerVideo duration in seconds. Value range: an integer in 1~15. Default: 5.
qualityRequiredstringVideo clarity. Value range: 360p / 540p / 720p / 1080p.
camera_movementOptionalstringCamera movement (for example zoom_in, use as needed).
seedOptionalintegerRandom seed. Value range: 0~2147483647. If omitted or set to 0, a random number is used.
generate_audio_switchOptionalbooleanAudio switch. true = with sound, false = muted. Default: false.
generate_multi_clip_switchOptionalbooleanMulti-shot switch, supported on pixverse-video-v6.0 only. true = multi-shot, false = single shot. Default: false.

Request Example โ€‹

bash
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 โ€‹

FieldTypeDescription
ErrCodeintegerError code; 0 indicates success.
ErrMsgstringError or informational message.
RespobjectResponse data object.
Resp.video_idstringVideo ID of the generation task, used for polling the task status.
request_idstringUnique request identifier used for troubleshooting.

Response Example โ€‹

json
{
  "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.

statusDescriptionRecommended handling
1Generation succeededRetrieve the resulting video from Resp.url.
5GeneratingPoll once every 3~5 seconds until status=1.
6DeletedThe task result has been deleted. Start the task again.
7Content moderation failedCheck whether the prompt/image contains prohibited content, revise it, and retry.
8Generation failedA 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 โ€‹

ParameterRequiredTypeDescription
promptRequiredstringText prompt describing the transition content. Value range: โ‰ค 5000 characters. Example: "transition naturally from the first frame to the last frame"
first_frame_imgRequiredstringFirst frame image address, which can be a publicly accessible image URL or base64 image data.
last_frame_imgRequiredstringLast frame image address, which can be a publicly accessible image URL or base64 image data.
modelRequiredstringModel version. Value range: pixverse-video-v6.0, pixverse-video-c1
durationRequiredintegerVideo duration in seconds. Value range: an integer in 1~15. Default: 5.
qualityRequiredstringVideo clarity. Value range: 360p / 540p / 720p / 1080p.
seedOptionalintegerRandom seed. Value range: 0~2147483647. If omitted or set to 0, a random number is used.
generate_audio_switchOptionalbooleanAudio switch. true = with sound, false = muted. Default: false.

Request Example โ€‹

bash
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 โ€‹

FieldTypeDescription
ErrCodeintegerError code; 0 indicates success.
ErrMsgstringError or informational message.
RespobjectResponse data object.
Resp.video_idstringTask ID used for polling the task status.
request_idstringUnique request identifier used for troubleshooting.

Response Example โ€‹

json
{
  "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.

statusDescriptionRecommended handling
1Generation succeededRetrieve the resulting video from Resp.url.
5GeneratingPoll once every 3~5 seconds until status=1.
6DeletedThe task result has been deleted. Start the task again.
7Content moderation failedCheck whether the prompt/image contains prohibited content, revise it, and retry.
8Generation failedA 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 โ€‹

ParameterRequiredTypeDescription
image_referencesRequiredarray[object]Array of reference images. Supports up to 7 entries. For subfields, see the table below.
promptRequiredstringText prompt. Value range: 5000 characters or fewer. Use @ref_name to reference an image (put a space after @). Example: "@dog plays in the @room".
modelRequiredstringModel version. Value range: pixverse-video-v6.0, pixverse-video-c1
durationRequiredintegerVideo duration in seconds. Value range: an integer in 1~15. Default: 5.
qualityRequiredstringVideo clarity. Value range: 360p / 540p / 720p / 1080p.
aspect_ratioOptionalstringAspect ratio. Value range: 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9. Default: 16:9.
generate_audio_switchOptionalbooleanAudio switch. true = with sound, false = muted. Default: false.
seedOptionalintegerRandom seed. Value range: 0~2147483647.

Subfields of the image_references array elements:

ParameterRequiredTypeDescription
img_idRequiredstringReference image address, which can be a publicly accessible image URL or base64 image data.
typeOptionalstringReference image type. Values: subject/background.
ref_nameOptionalstringReference image name, which must be 30 characters or fewer. Used to reference it as @ref_name in the prompt.

Request Example โ€‹

bash
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 โ€‹

FieldTypeDescription
ErrCodeintegerError code; 0 indicates success.
ErrMsgstringError or informational message.
RespobjectResponse data object.
Resp.video_idstringTask ID used for polling the task status.
request_idstringUnique request identifier used for troubleshooting.

Response Example โ€‹

json
{
  "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.

statusDescriptionRecommended handling
1Generation succeededRetrieve the resulting video from Resp.url.
5GeneratingPoll once every 3~5 seconds until status=1.
6DeletedThe task result has been deleted. Start the task again.
7Content moderation failedCheck whether the prompt/image contains prohibited content, revise it, and retry.
8Generation failedA 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 โ€‹

ParameterRequiredTypeDescription
task_idRequiredstringTask ID (path parameter), that is, the Resp.video_id returned when the task was submitted.

Request Example โ€‹

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

Response Parameters โ€‹

FieldTypeDescription
ErrCodeintegerError code; 0 indicates success.
ErrMsgstringError or informational message
RespobjectResponse data object (task details)
Resp.idstringVideo ID (video_id)
Resp.statusintegerVideo status: 1 succeeded / 5 generating / 6 deleted / 7 moderation failed / 8 generation failed
Resp.urlstringURL of the video result after generation succeeds
Resp.promptstringPrompt used for this generation
Resp.negative_promptstringNegative prompt
Resp.seedintegerRandom seed
Resp.stylestringStyle
Resp.resolution_ratiointegerVideo clarity
Resp.outputWidthintegerVideo width
Resp.outputHeightintegerVideo height
Resp.sizeintegerVideo file size
Resp.create_timestringTask creation time.
Resp.modify_timestringTask update time.
tokenhub_usageobjectUsage
tokenhub_usage.total_tokensintegerNumber of tokens used
request_idstringUnique request identifier used for troubleshooting.

Response Example โ€‹

Generation succeeded:

json
{
  "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 โ€‹

statusDescriptionRecommended handling
1Generation succeededRetrieve the resulting video from Resp.url.
5GeneratingPoll once every 3~5 seconds until status=1.
6DeletedThe task result has been deleted. Start the task again.
7Content moderation failedCheck whether the prompt/image contains prohibited content, revise it, and retry.
8Generation failedA 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 โ€‹

ParameterDescription
durationAn integer in 1~15 (1080p also supports up to 15 seconds).
aspect_ratioSupported 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_switchSupported 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.

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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages