跳到内容

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.0360p / 540p / 720p / 1080p16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:91 ~ 15 秒
pixverse-video-c1360p / 540p / 720p / 1080p16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 2:3 / 3:2 / 21:91 ~ 15 秒

输入模式 ​

版本输入
pixverse-video-v6.0文生视频 / 图生视频 / 首帧/尾帧 / 基于参考生成
pixverse-video-c1文生视频 / 图生视频 / 首帧/尾帧 / 基于参考生成

调用流程 ​

视频生成是耗时较长的任务(一般为 1~5 分钟)。API采用异步调用方式,分为以下两个步骤。

  1. 提交任务:调用功能 API(文生视频/图生视频/首帧/尾帧生视频/参考生视频)。成功后会返回 Resp.video_id(任务 ID)。
  2. 轮询结果:用 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。

请求示例 ​

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"
}'

注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。

响应参数 ​

字段类型说明
ErrCodeinteger错误码,0 表示成功。
ErrMsgstring错误或提示信息。
Respobject响应数据对象。
Resp.video_idstring用于轮询任务状态的任务 ID。
request_idstring用于排查问题的唯一请求标识符。

响应示例 ​

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

请求示例 ​

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"
}'

注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。

响应参数 ​

字段类型说明
ErrCodeinteger错误码,0 表示成功。
ErrMsgstring错误或提示信息。
Respobject响应数据对象。
Resp.video_idstring生成任务的视频 ID,用于轮询查询任务状态。
request_idstring用于排查问题的唯一请求标识符。

响应示例 ​

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

请求示例 ​

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"
}'

注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。

响应参数 ​

字段类型说明
ErrCodeinteger错误码,0 表示成功。
ErrMsgstring错误或提示信息。
Respobject响应数据对象。
Resp.video_idstring用于轮询任务状态的任务 ID。
request_idstring用于排查问题的唯一请求标识符。

响应示例 ​

json
{
  "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 引用。

请求示例 ​

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"
}'

注意: 若要调用相应模型,请把示例中的 model 换成 pixverse-video-c1。

响应参数 ​

字段类型说明
ErrCodeinteger错误码,0 表示成功。
ErrMsgstring错误或提示信息。
Respobject响应数据对象。
Resp.video_idstring用于轮询任务状态的任务 ID。
request_idstring用于排查问题的唯一请求标识符。

响应示例 ​

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

请求示例 ​

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

响应参数 ​

字段类型说明
ErrCodeinteger错误码,0 表示成功。
ErrMsgstring错误或提示信息
Respobject响应数据对象(任务详细信息)
Resp.idstring视频 ID(video_id)
Resp.statusinteger视频状态:1 成功 / 5 生成中 / 6 已删除 / 7 审核失败 / 8 生成失败
Resp.urlstring生成成功后的视频结果 URL
Resp.promptstring本次生成使用的提示词
Resp.negative_promptstring负向提示词
Resp.seedinteger随机数种子
Resp.stylestring风格
Resp.resolution_ratiointeger视频清晰度
Resp.outputWidthinteger视频宽度
Resp.outputHeightinteger视频高度
Resp.sizeinteger视频文件大小
Resp.create_timestring任务创建时间。
Resp.modify_timestring任务更新时间。
tokenhub_usageobject使用量
tokenhub_usage.total_tokensinteger已使用的 token 数
request_idstring用于排查问题的唯一请求标识符。

响应示例 ​

生成成功:

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说明处理建议
1生成成功从 Resp.url 获取结果视频。
5生成中每 3~5 秒 轮询一次,直到 status=1。
6已删除任务结果已被删除,请重新发起任务。
7内容审核失败请检查提示词/图片是否含违禁内容,修改后重试。
8生成失败服务端生成出错,请重试请求。若持续失败,请联系技术支持团队并提供任务 ID。

附录:通用参数限制速查 ​

参数说明
duration1~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 小时,请尽快下载保存。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages