PixVerse
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video认证: Tokenhub API Key / Bearer
PixVerse 是视频生成模型,支持通过文本、图片、首帧 / 尾帧以及参考图输入生成视频。提交任务后用任务 ID 查询结果。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 护栏解除支持 | 不支持 |
各版本支持规格
| 版本 | 分辨率 | 比例 | 时长 |
|---|---|---|---|
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 秒 |
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 秒 |
输入模式
| 版本 | 输入 |
|---|---|
pixverse-video-v6.0 | 文生视频 / 图生视频 / 首帧/尾帧 / 基于参考生成 |
pixverse-video-c1 | 文生视频 / 图生视频 / 首帧/尾帧 / 基于参考生成 |
调用流程
视频生成是耗时较长的任务(一般为 1~5 分钟)。API采用异步调用方式,分为以下两个步骤。
- 提交任务:调用功能 API(文生视频/图生视频/首帧/尾帧生视频/参考生视频)。成功后会返回
Resp.video_id(任务 ID)。 - 轮询结果:用
video_id调用任务结果查询 API。建议每3~5 秒轮询一次,直到变为Resp.status = 1(生成成功),然后从Resp.url获取结果视频。
注意: 任务成功创建后请勿重复提交,改用轮询获取结果。通用响应格式:ErrCode(0 表示成功)、ErrMsg(消息)、Resp(数据对象)。
文生视频
API 说明
仅凭文本提示词生成视频,支持镜头运动、音频及多镜头开关。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/text-to-video
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| prompt | 必填 | string | 描述所需视频内容的文本提示词。取值范围:≤ 5000 字。 |
| model | 必填 | string | 模型版本。取值范围:pixverse-video-v6.0, pixverse-video-c1 |
| duration | 必填 | integer | 视频时长(秒)。取值范围:1~15 的整数。默认值:5。 |
| quality | 必填 | string | 视频清晰度。取值范围:360p / 540p / 720p / 1080p。 |
| aspect_ratio | 可选 | string | 比例。取值范围:16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9。默认值:16:9。 |
| camera_movement | 可选 | string | 镜头运动(例如 zoom_in,按需使用)。 |
| seed | 可选 | integer | 随机数种子。取值范围:0~2147483647。不指定或设为 0 时使用随机数。 |
| generate_audio_switch | 可选 | boolean | 音频开关。true=有声(自动生成匹配的背景音乐或音效),false=静音。默认值:false。 |
| generate_multi_clip_switch | 可选 | boolean | 多镜头开关,仅 pixverse-video-v6.0 支持。true=多镜头(系统智能分镜),false=单镜头。默认值:false。 |
请求示例
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"
}'注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| ErrCode | integer | 错误码,0 表示成功。 |
| ErrMsg | string | 错误或提示信息。 |
| Resp | object | 响应数据对象。 |
| Resp.video_id | string | 用于轮询任务状态的任务 ID。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
响应示例
{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"video_id": "4-WandVideo-4ba31a7d508249b787fa0b0c62a6a399"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}错误码
请求失败时 ErrCode 不为 0。具体原因请参考 ErrMsg。任务提交成功后,可通过「任务结果查询」API 获取生成阶段的任务状态。
| status | 说明 | 处理建议 |
|---|---|---|
1 | 生成成功 | 从 Resp.url 获取结果视频。 |
5 | 生成中 | 每 3~5 秒 轮询一次,直到 status=1。 |
6 | 已删除 | 任务结果已被删除,请重新发起任务。 |
7 | 内容审核失败 | 请检查提示词/图片是否含违禁内容,修改后重试。 |
8 | 生成失败 | 服务端生成出错,请重试请求。若持续失败,请联系技术支持团队并提供任务 ID。 |
图生视频
API 说明
以图片作为首帧生成有动态效果的视频。直接传入可公开访问的 URL 图片,输出视频的比例与输入图片的比例一致。支持负向提示词、镜头运动、音频及多镜头开关。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/image-to-video
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| img_id | 必填 | string | 图片地址,可以是可公开访问的图片 URL 或 base64 图片数据。 |
| img_ids | 可选 | array[string] | 多图模板专用的图片 URL 数组(例如 ["url1", "url2"])。 |
| prompt | 必填 | string | 文本提示词。取值范围:≤ 5000 字。 |
| model | 必填 | string | 模型版本。取值范围:pixverse-video-v6.0, pixverse-video-c1 |
| duration | 必填 | integer | 视频时长(秒)。取值范围:1~15 的整数。默认值:5。 |
| quality | 必填 | string | 视频清晰度。取值范围:360p / 540p / 720p / 1080p。 |
| camera_movement | 可选 | string | 镜头运动(例如 zoom_in,按需使用)。 |
| seed | 可选 | integer | 随机数种子。取值范围:0~2147483647。不指定或设为 0 时使用随机数。 |
| generate_audio_switch | 可选 | boolean | 音频开关。true=有声,false=静音。默认值:false。 |
| generate_multi_clip_switch | 可选 | boolean | 多镜头开关,仅 pixverse-video-v6.0 支持。true=多镜头,false=单镜头。默认值:false。 |
请求示例
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"
}'注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| ErrCode | integer | 错误码,0 表示成功。 |
| ErrMsg | string | 错误或提示信息。 |
| Resp | object | 响应数据对象。 |
| Resp.video_id | string | 生成任务的视频 ID,用于轮询查询任务状态。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
响应示例
{
"ErrCode": 0,
"ErrMsg": "success",
"Resp": {
"video_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}错误码
请求失败时 ErrCode 不为 0。具体原因请参考 ErrMsg。任务提交成功后,可通过「任务结果查询」API 获取生成阶段的任务状态。
| status | 说明 | 处理建议 |
|---|---|---|
1 | 生成成功 | 从 Resp.url 获取结果视频。 |
5 | 生成中 | 每 3~5 秒 轮询一次,直到 status=1。 |
6 | 已删除 | 任务结果已被删除,请重新发起任务。 |
7 | 内容审核失败 | 请检查提示词/图片是否含违禁内容,修改后重试。 |
8 | 生成失败 | 服务端生成出错,请重试请求。若持续失败,请联系技术支持团队并提供任务 ID。 |
首帧及尾帧生视频
Start End To Video
将两张图片指定为首帧及尾帧(可公开访问的 URL),生成在两帧之间自然过渡的视频。输出视频的比例与输入图片的比例一致。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/start-end-to-video
注意: 为获得最佳过渡效果,建议让首帧与尾帧图片的比例保持一致。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| prompt | 必填 | string | 描述过渡内容的文本提示词。取值范围:≤ 5000 字。例:"从首帧自然过渡到尾帧" |
| first_frame_img | 必填 | string | 首帧图片地址,可以是可公开访问的图片 URL 或 base64 图片数据。 |
| last_frame_img | 必填 | string | 尾帧图片地址,可以是可公开访问的图片 URL 或 base64 图片数据。 |
| model | 必填 | string | 模型版本。取值范围:pixverse-video-v6.0, pixverse-video-c1 |
| duration | 必填 | integer | 视频时长(秒)。取值范围:1~15 的整数。默认值:5。 |
| quality | 必填 | string | 视频清晰度。取值范围:360p / 540p / 720p / 1080p。 |
| seed | 可选 | integer | 随机数种子。取值范围:0~2147483647。不指定或设为 0 时使用随机数。 |
| generate_audio_switch | 可选 | boolean | 音频开关。true=有声,false=静音。默认值:false。 |
请求示例
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"
}'注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| ErrCode | integer | 错误码,0 表示成功。 |
| ErrMsg | string | 错误或提示信息。 |
| Resp | object | 响应数据对象。 |
| Resp.video_id | string | 用于轮询任务状态的任务 ID。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
响应示例
{
"ErrCode": 0,
"ErrMsg": "success",
"Resp": {
"video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}错误码
请求失败时 ErrCode 不为 0。具体原因请参考 ErrMsg。任务提交成功后,可通过「任务结果查询」API 获取生成阶段的任务状态。
| status | 说明 | 处理建议 |
|---|---|---|
1 | 生成成功 | 从 Resp.url 获取结果视频。 |
5 | 生成中 | 每 3~5 秒 轮询一次,直到 status=1。 |
6 | 已删除 | 任务结果已被删除,请重新发起任务。 |
7 | 内容审核失败 | 请检查提示词/图片是否含违禁内容,修改后重试。 |
8 | 生成失败 | 服务端生成出错,请重试请求。若持续失败,请联系技术支持团队并提供任务 ID。 |
参考生视频
API 说明
结合参考图片集(参考对象/背景)与提示词,生成能保持参考对象一致性的视频。参考图片直接以可公开访问的 URL 传入,并可在提示词中用 @ref_name 指代特定参考图片。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/reference-to-video
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| image_references | 必填 | array[object] | 参考图片数组。最多支持 7 个 项。子字段请参考下表。 |
| prompt | 必填 | string | 文本提示词。取值范围:5000 字以内。用 @ref_name 引用图片(@ 后要带空格)。例:"@dog 在 @room 里玩"。 |
| model | 必填 | string | 模型版本。取值范围:pixverse-video-v6.0, pixverse-video-c1 |
| duration | 必填 | integer | 视频时长(秒)。取值范围:1~15 的整数。默认值:5。 |
| quality | 必填 | string | 视频清晰度。取值范围:360p / 540p / 720p / 1080p。 |
| aspect_ratio | 可选 | string | 比例。取值范围:16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9。默认值:16:9。 |
| generate_audio_switch | 可选 | boolean | 音频开关。true=有声,false=静音。默认值:false。 |
| seed | 可选 | integer | 随机数种子。取值范围:0~2147483647。 |
image_references 数组元素的子字段:
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| img_id | 必填 | string | 参考图片地址,可以是可公开访问的图片 URL 或 base64 图片数据。 |
| type | 可选 | string | 参考图片类型。取值:subject/background。 |
| ref_name | 可选 | string | 参考图片名称,须在 30 字以内。用于在提示词中以 @ref_name 引用。 |
请求示例
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"
}'注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| ErrCode | integer | 错误码,0 表示成功。 |
| ErrMsg | string | 错误或提示信息。 |
| Resp | object | 响应数据对象。 |
| Resp.video_id | string | 用于轮询任务状态的任务 ID。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
响应示例
{
"ErrCode": 0,
"ErrMsg": "success",
"Resp": {
"video_id": "1374200019-WandVideo-a786becfdc80433b8cff4aa344c8fd3d"
},
"request_id": "4d384c85-2177-4bae-adf9-364ed917509b"
}错误码
请求失败时 ErrCode 不为 0。具体原因请参考 ErrMsg。任务提交成功后,可通过「任务结果查询」API 获取生成阶段的任务状态。
| status | 说明 | 处理建议 |
|---|---|---|
1 | 生成成功 | 从 Resp.url 获取结果视频。 |
5 | 生成中 | 每 3~5 秒 轮询一次,直到 status=1。 |
6 | 已删除 | 任务结果已被删除,请重新发起任务。 |
7 | 内容审核失败 | 请检查提示词/图片是否含违禁内容,修改后重试。 |
8 | 生成失败 | 服务端生成出错,请重试请求。若持续失败,请联系技术支持团队并提供任务 ID。 |
任务结果查询
API 说明
四项功能 API 共用的任务查询 API,用于轮询生成结果。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/tasks/{task_id}
注意: 路径中的 {task_id} 是提交任务时返回的 Resp.video_id。视频生成约需数分钟,建议每 3~5 秒 轮询一次。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 任务 ID(路径参数),即提交任务时返回的 Resp.video_id。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/pixverse/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| ErrCode | integer | 错误码,0 表示成功。 |
| ErrMsg | string | 错误或提示信息 |
| Resp | object | 响应数据对象(任务详细信息) |
| Resp.id | string | 视频 ID(video_id) |
| Resp.status | integer | 视频状态:1 成功 / 5 生成中 / 6 已删除 / 7 审核失败 / 8 生成失败 |
| Resp.url | string | 生成成功后的视频结果 URL |
| Resp.prompt | string | 本次生成使用的提示词 |
| Resp.negative_prompt | string | 负向提示词 |
| Resp.seed | integer | 随机数种子 |
| Resp.style | string | 风格 |
| Resp.resolution_ratio | integer | 视频清晰度 |
| Resp.outputWidth | integer | 视频宽度 |
| Resp.outputHeight | integer | 视频高度 |
| Resp.size | integer | 视频文件大小 |
| Resp.create_time | string | 任务创建时间。 |
| Resp.modify_time | string | 任务更新时间。 |
| tokenhub_usage | object | 使用量 |
| tokenhub_usage.total_tokens | integer | 已使用的 token 数 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
响应示例
生成成功:
{
"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 | 说明 | 处理建议 |
|---|---|---|
1 | 生成成功 | 从 Resp.url 获取结果视频。 |
5 | 生成中 | 每 3~5 秒 轮询一次,直到 status=1。 |
6 | 已删除 | 任务结果已被删除,请重新发起任务。 |
7 | 内容审核失败 | 请检查提示词/图片是否含违禁内容,修改后重试。 |
8 | 生成失败 | 服务端生成出错,请重试请求。若持续失败,请联系技术支持团队并提供任务 ID。 |
附录:通用参数限制速查
| 参数 | 说明 |
|---|---|
| duration | 1~15 的整数(1080p 也最多支持 15 秒)。 |
| aspect_ratio | 仅文生视频及参考生视频支持。取值:16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:9,默认值:16:9。图生视频及首帧/尾帧生视频不支持该参数,输出比例与输入图片的比例一致。 |
| generate_multi_clip_switch | 仅 pixverse-video-v6.0 的文生视频及图生视频支持,首帧/尾帧及参考生视频不支持。 |
常见问题
1. 两个模型该选哪一个?
- 一般场景或需要多镜头智能分镜时:
pixverse-video-v6.0。 - 战斗、魔法特效、高速运动这类动态场景:
pixverse-video-c1。
2. 图生视频、首帧/尾帧及参考生视频 API 要怎么传入图片?
可以直接传入可公开访问的图片 URL。img_id(图生视频)、first_frame_img / last_frame_img(首帧及尾帧)、image_references.img_id(参考生视频)都能接收图片 URL 字符串,无需先调用上传 API。
3. 生成的视频链接有有效期吗?
URL 会过期。任务成功后请立即从 Resp.url 下载视频文件。有效期不超过 12 小时,请尽快下载保存。