获取特效模板列表
概览
GET /openapi/v2/video/effects/templates/list前置条件
操作步骤
请求 Header
| 字段 | 类型 | 必传 | 说明 |
|---|---|---|---|
| API-KEY | string | 是 | PixVerse API Key，客户注册后获取 |
| Ai-trace-id | string | 是 | 请求 trace id，每次请求建议唯一 |
| Accept-Language | string | 否 | 语言标识。支持: zh-CN, en。传入后会按 header 中的语言顺序查找模板多语言配置并优先返回该语言配置；未命中则返回默认字段 |
请求 Query 参数
| 字段 | 类型 | 必传 | 说明 |
|---|---|---|---|
| type | string | 否 | 模板类型，1 为视频模板，2 为图片模板；不传返回全部 |
| page | string | 否 | 页码，不传默认 1 |
| pageSize | string | 否 | 每页数量，不传默认 50；传入时仅支持 10、20、50、100，其他值返回参数错误 |
| template_ids | string | 否 | 模板ID，支持批量传入，逗号隔开 |
GET /openapi/v2/video/effects/templates/list?type=1&page=1&pageSize=20
Accept-Language: zh-CN响应字段
顶层字段
| 字段 | 类型 | 说明 |
|---|---|---|
| ErrCode | integer | 错误码，0 表示成功 |
| ErrMsg | string | 错误信息 |
| Resp | object | 响应数据 |
Resp 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| effect_items | array<object> | 模板特效列表 |
effect_items 字段
| 字段含义 | 字段名称 | 类型 | 示例 | 说明 |
|---|---|---|---|---|
| 模板 ID | template_id | integer | 402331965264704 | 用于生成接口传入 template_id |
| 模板名 | display_name | string | 观众席抓拍 | 模板展示名称；传入 `Accept-Language` 且存在对应多语言配置时优先返回该语言配置 |
| 模板提示 | display_prompt | string | 生成电影感观众席反应镜头。 | 用于模板展示；传入 `Accept-Language` 且存在对应多语言配置时优先返回该语言配置 |
| 视频链接 | thumbnail_video_url | string | https://media\.pixverse\.ai/\.\.\.mp4 | 模板预览视频 |
| 分辨率 | qualities | array<string> | ["360p","540p","720p","1080p"] | 模板支持分辨率 |
| 图片数量 | effect_type | string | "1" | 模板所需输入图片数量 |
| 模板支持时长 | effect_length | array<int> | [8] | 固定时长模板返回固定时长；非固定时长按现有规则返回 |
| 输入说明 | topic_requirements | string | 主体类型：人物\n建议主体数量：1-2 | 模板输入素材要求说明 |
| 模板类型 | type | integer | 1 | 1 为视频模板，2 为图片模板 |
| 模板创建时间 | create_at | string | 2026-06-11 14:43:28 | 按创建时间倒序返回 |
| 计费 | credit_consume | array<object> | [{"consume_desc_key":"360p","credit":"55"}] | 不同分辨率对应消耗 |
credit_consume 字段
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
| consume_desc_key | string | 360p | 计费维度 |
| credit | string | 55 | 消耗 credits 数量 |
响应示例
{
"ErrCode": 0,
"ErrMsg": "Success",
"Resp": {
"effect_items": [
{
"template_id": 402331965264704,
"display_name": "观众席抓拍",
"display_prompt": "生成电影感观众席反应镜头。",
"thumbnail_video_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fstands_cam_capture.mp4",
"qualities": [
"360p",
"540p",
"720p",
"1080p"
],
"effect_type": "1",
"effect_length": [
8
],
"topic_requirements": "主体类型：人物\n建议主体数量：1-2",
"type": 1,
"create_at": "2026-06-11 14:43:28",
"credit_consume": [
{
"consume_desc_key": "360p",
"credit": "55"
},
{
"consume_desc_key": "540p",
"credit": "78"
},
{
"consume_desc_key": "720p",
"credit": "100"
},
{
"consume_desc_key": "1080p",
"credit": "190"
}
]
},
{
"template_id": 402331965264705,
"display_name": "老照片复活",
"display_prompt": "让老照片中的人物自然动起来，并呈现温暖的电影光感。",
"thumbnail_video_url": "https://media.pixverse.ai/asset%2Ftemplate%2Fvintage_photo_revival.mp4",
"qualities": [
"360p",
"540p",
"720p",
"1080p"
],
"effect_type": "1",
"effect_length": [
5
],
"topic_requirements": "主体类型：人物\n建议主体数量：1",
"type": 1,
"create_at": "2026-06-10 11:20:00",
"credit_consume": [
{
"consume_desc_key": "360p",
"credit": "50"
},
{
"consume_desc_key": "540p",
"credit": "75"
},
{
"consume_desc_key": "720p",
"credit": "100"
},
{
"consume_desc_key": "1080p",
"credit": "180"
}
]
}
]
}
}错误响应
| 场景 | 错误说明 |
|---|---|
| Header 缺失或 API Key 无效 | 返回鉴权失败错误 |
| 账号请求超过限流阈值 | 返回 ErrCode=712008，提示请求过快 |
| 参数格式错误，或 pageSize 传入非 10、20、50、100 的值 | 返回参数错误 |
{
"ErrCode": 10005,
"ErrMsg": "apiKey is not registered"
}{
"ErrCode": 712008,
"ErrMsg": "Request too fast. Please try again later."
}{
"ErrCode": 400017,
"ErrMsg": "Invalid field: pageSize"
}修改于 2026-07-30 08:31:42