Get template list

Feature Overview

The Effects Template List API returns all publicly available templates that are currently supported through OpenAPI, along with structured template metadata. This helps users select the appropriate template when generating videos or images.

Endpoint: GET /openapi/v2/video/effects/templates/list

Prerequisites

Before getting started, make sure you have:

A valid PixVerse API key

A unique Ai-trace-id for each API request

API Description

This API only returns templates that are currently available for use through OpenAPI.

Results are sorted by template creation time in descending order by default

Newly created templates are returned first

Rate Limit

This API is rate-limited at the account level

The default QPS is 1

If the request rate exceeds the limit, the API returns ErrCode=712008

If you need a higher QPS limit, please contact the PixVerse business team

Usage

1. Request the Effects Template List

Request path:

GET /openapi/v2/video/effects/templates/list

Request headers

Field	Type	Required	Value Description	Notes
`API-KEY`	`string`	Yes	PixVerse API key	Available after registration
`Ai-trace-id`	`string`	Yes	Any string, recommended to be unique	Request trace ID; a unique value is recommended for each request
`Accept-Language`	`string`	No	For example: `zh-CN`, `en`	Language identifier. If provided, the API looks up multilingual template configuration based on the language order in the header. Otherwise, default values are returned

Query parameters

Field	Type	Required	Value Description	Notes
`type`	`string`	No	`1` / `2`	Template type. `1` for video templates, `2` for image templates. If omitted, all templates are returned
`page`	`string`	No	Positive integer	Page number. Defaults to `1`
`pageSize`	`string`	No	`10`, `20`, `50`, `100`	Number of items per page. Defaults to `50`. Any other value results in a parameter error

Example request

2. Response Fields

Top-level response fields

Field	Type	Description
`ErrCode`	`integer`	Error code. `0` indicates success
`ErrMsg`	`string`	Error message
`Resp`	`object`	Response payload

Resp fields

Field	Type	Description
`effect_items`	`array<object>`	List of effect templates

effect_items fields

Field Meaning	Field Name	Type	Example	Notes
Template ID	`template_id`	`integer`	`402331965264704`	Can be passed as `template_id` in generation APIs
Template name	`display_name`	`string`	`Audience Reaction Shot`	Display name of the template. If `Accept-Language` is provided and a matching localization exists, the localized value is returned first
Template prompt	`display_prompt`	`string`	`Generate a cinematic audience reaction shot.`	Used for template display. If `Accept-Language` is provided and a matching localization exists, the localized value is returned first
Preview video URL	`thumbnail_video_url`	`string`	`https://media.pixverse.ai/...mp4`	Template preview video
Resolutions	`qualities`	`array<string>`	`["360p","540p","720p","1080p"]`	Supported output resolutions
Image count	`effect_type`	`string`	`"1"`	Number of input images required by the template
Supported duration	`effect_length`	`array<int>`	`[8]`	Fixed-duration templates return a fixed value; non-fixed-duration templates return values based on current rules
Input requirements	`topic_requirements`	`string`	`Subject type: person\nRecommended subject count: 1-2`	Requirements for input assets
Template type	`type`	`integer`	`1`	`1` for video templates, `2` for image templates
Template creation time	`create_at`	`string`	`2026-06-11 14:43:28`	Returned in descending order by creation time
Pricing	`credit_consume`	`array<object>`	`[{"consume_desc_key":"360p","credit":"55"}]`	Credit consumption for different resolutions

credit_consume fields

Field	Type	Example	Notes
`consume_desc_key`	`string`	`360p`	Billing dimension
`credit`	`string`	`55`	Number of credits consumed

3. Response Example

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "effect_items": [
      {
        "template_id": 402331965264704,
        "display_name": "Audience Reaction Shot",
        "display_prompt": "Generate a cinematic audience reaction shot.",
        "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": "Subject type: person\nRecommended subject count: 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"
          }
        ]
      }
    ]
  }
}

Error Responses

This API uses the common OpenAPI error response format.

Common error scenarios

Scenario	Description
Missing header or invalid API key	Returns an authentication error
Request rate exceeds the account limit	Returns `ErrCode=712008`, indicating the request is too frequent
Invalid parameter format, or `pageSize` is not one of `10`, `20`, `50`, `100`	Returns a parameter error

Authentication error example

{
  "ErrCode": 10005,
  "ErrMsg": "apiKey is not registered"
}

Rate limit error example

{
  "ErrCode": 712008,
  "ErrMsg": "Request too fast. Please try again later."
}

Parameter error example

{
  "ErrCode": 400017,
  "ErrMsg": "Invalid field: pageSize"
}

Feature Overview#

Prerequisites#

API Description#

Rate Limit#

Usage#

1. Request the Effects Template List#

2. Response Fields#

3. Response Example#

Error Responses#