# 查询版权 IP 模板列表
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
`POST https://ark.cn-beijing.volcengineapi.com/?Action=ListIPTemplates&Version=2024-01-01`
查询当前账号可用的版权 IP 模板列表。模板创作场景下，可先调用本接口获取模板 ID、模板内容和可替换素材要求，再调用 [创建视频生成任务 API](/docs/create-video-generation-task-api) 生成版权 IP 视频。详细流程请参考 [使用视频生成 API 创作版权 IP 视频](/docs/copyright-video-api)。
> **说明**
>
> `ListIPTemplates` API 支持按 IP ID（`Filter.IPIds[]`）筛选结果。
## 鉴权
本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。
* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。
---
## 请求参数
### Body 参数
**Filter** `object` | 过滤条件
查询过滤条件。可按模板 ID、IP ID 或关键词筛选模板。
**IPIds** `string[]` | IP ID 列表
`Filter.IPIds`
按 IP ID 列表筛选版权 IP 模板。支持 `ip-c-*` 和 `ip-s-*` 前缀。
**Keyword** `string` | 关键词
`Filter.Keyword`
按关键词筛选版权 IP 模板。
**TemplateIds** `string[]` | 模板 ID 列表
`Filter.TemplateIds`
按模板 ID 列表筛选版权 IP 模板。
**Page** `object` | 分页参数
**PageNumber** `integer` `必选` | 页码
`Page.PageNumber`
分页查询时的页码，从 1 开始。
**PageSize** `integer` `必选` | 每页数量
`Page.PageSize`
分页查询时每页返回的记录数。
**Sort** `object` | 排序参数
**SortBy** `string` `必选` | 排序字段
`Sort.SortBy`
用于排序的字段名称。
**SortOrder** `string` `必选` | 排序顺序
`Sort.SortOrder`
排序顺序。可选值：`Desc`、`Asc`。
## 响应参数
**items** `object[]` | 模板列表
版权 IP 模板列表。
**display_content** `object[]` | 展示内容
`items.display_content`
模板完整内容，用于展示模板内置提示词、固定素材和可替换素材。
**order** `integer` | 元素顺序
`items.display_content.order`
内容元素顺序。可替换素材使用从 0 开始的顺序，固定素材使用 `-1`。
**type** `string` | 内容类型
`items.display_content.type`
内容元素类型。可选值：`text`、`image_url`、`video_url`、`audio_url`。
**audio_url** `object` | 音频信息
`items.display_content.audio_url`
音频素材信息。*type* 为 `audio_url` 时返回。
**url** `string` | 音频 URL
`items.display_content.audio_url.url`
音频素材的可访问 URL。
**image_url** `object` | 图片信息
`items.display_content.image_url`
图片素材信息。*type* 为 `image_url` 时返回。
**url** `string` | 图片 URL
`items.display_content.image_url.url`
图片素材的可访问 URL。
**replaceable** `boolean` | 是否可替换
`items.display_content.replaceable`
表示该内容元素是否允许用户替换。
**role** `string` | 素材角色
`items.display_content.role`
素材在视频生成请求中的角色。创建视频生成任务时，将该值原样填入 *content[]*.role。
**text** `string` | 文本内容
`items.display_content.text`
文本内容。*type* 为 `text` 时返回。
**video_url** `object` | 视频信息
`items.display_content.video_url`
视频素材信息。*type* 为 `video_url` 时返回。
**url** `string` | 视频 URL
`items.display_content.video_url.url`
视频素材的可访问 URL。
**template_content** `object[]` | 可替换素材
`items.template_content`
调用方需要准备并传入视频生成 API 的可替换素材列表。
**order** `integer` | 元素顺序
`items.template_content.order`
内容元素顺序。可替换素材使用从 0 开始的顺序，固定素材使用 `-1`。
**type** `string` | 内容类型
`items.template_content.type`
内容元素类型。可选值：`text`、`image_url`、`video_url`、`audio_url`。
**audio_url** `object` | 音频信息
`items.template_content.audio_url`
音频素材信息。*type* 为 `audio_url` 时返回。
**url** `string` | 音频 URL
`items.template_content.audio_url.url`
音频素材的可访问 URL。
**description** `string` | 用途说明
`items.template_content.description`
素材用途说明。
**image_url** `object` | 图片信息
`items.template_content.image_url`
图片素材信息。*type* 为 `image_url` 时返回。
**url** `string` | 图片 URL
`items.template_content.image_url.url`
图片素材的可访问 URL。
**role** `string` | 素材角色
`items.template_content.role`
素材在视频生成请求中的角色。创建视频生成任务时，将该值原样填入 *content[]*.role。
**text** `string` | 文本内容
`items.template_content.text`
文本内容。*type* 为 `text` 时返回。
**video_url** `object` | 视频信息
`items.template_content.video_url`
视频素材信息。*type* 为 `video_url` 时返回。
**url** `string` | 视频 URL
`items.template_content.video_url.url`
视频素材的可访问 URL。
**template_id** `string` | 模板 ID
`items.template_id`
版权 IP 模板 ID。创建视频生成任务时，需将该值传入 *moderation_options.commercial_ip_template*。
**default_params** `object` | 默认参数
`items.default_params`
如视频生成请求中不传入对应参数，则默认使用模板返回的 `default_params` 参数值。您可在请求中根据需求指定其他值。
**duration** `integer` | 视频时长
`items.default_params.duration`
模板推荐的视频时长，单位为秒。创建视频生成任务时，可将该值映射到请求参数 *duration*。
**ratio** `string` | 宽高比
`items.default_params.ratio`
模板推荐的视频宽高比。创建视频生成任务时，可将该值映射到请求参数 *ratio*。
**resolution** `string` | 分辨率
`items.default_params.resolution`
模板推荐的视频分辨率。创建视频生成任务时，可将该值映射到请求参数 *resolution*。
**watermark** `boolean` | 水印配置
`items.default_params.watermark`
模板推荐的视频水印配置。创建视频生成任务时，可将该值映射到请求参数 *watermark*。
**ip_id** `string` | IP ID
`items.ip_id`
模板关联的 IP ID，由版权 ID 转换得到。
**total** `integer` | 总数
符合筛选条件的模板总数。
## 代码示例
## 默认
### cURL
#### Request
```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=ListIPTemplates&Version=2024-01-01' \
-H 'Content-Type: application/json' \
-H 'X-Date: ' \
-H 'X-Content-Sha256: ' \
-H 'Authorization: HMAC-SHA256 Credential=//cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=' \
-d '{
"Filter": {
"TemplateIds": [
"tpl-copyright-ip-20260501-a1b2c"
],
"IPIds": [
"ip-c-20260420-x9y8z"
],
"Keyword": "国潮舞蹈"
},
"Page": {
"PageNumber": 1,
"PageSize": 10
},
"Sort": {
"SortBy": "CreateTime",
"SortOrder": "Desc"
}
}
'
```
#### Response
```
{
"ResponseMetadata": {
"RequestId": "20260501132104E4A88203DB6C57F195",
"Action": "ListIPTemplates",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"total": 1,
"items": [
{
"template_id": "tpl-copyright-ip-20260501-a1b2c",
"ip_id": "ip-c-20260420-x9y8z",
"default_params": {
"ratio": "16:9",
"resolution": "1080p",
"duration": 5,
"watermark": true
},
"display_content": [
{
"type": "text",
"text": "国潮少女在紫禁城前起舞，镜头缓缓推进",
"order": -1,
"replaceable": false
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-content-generation.example.com/copyright-ip/display/character-front.png"
},
"role": "first_frame",
"order": 0,
"replaceable": true
},
{
"type": "audio_url",
"audio_url": {
"url": "https://ark-content-generation.example.com/copyright-ip/display/theme-bgm.mp3"
},
"role": "bgm",
"order": -1,
"replaceable": false
}
],
"template_content": [
{
"type": "image_url",
"image_url": {
"url": "https://ark-content-generation.example.com/copyright-ip/replaceable/character-placeholder.png"
},
"role": "first_frame",
"order": 0,
"description": "主角首帧图，建议 1024x1024 及以上，人物居中"
}
]
}
]
}
}
```