Growth Studio OpenAPI Integration Guide · 模板创作
Choose a platform-provided template and submit product information and template parameters to generate one product video asynchronously. The catalog supplies display content, input declarations, and pricing rules so you can build a template picker and input form in your own product.
Use the following endpoints for new integrations. Every request requires Authorization: Bearer <API_KEY>. The API key identifies the account and workspace; do not send account or workspace IDs in the request.
| Method | Path | Purpose |
|---|---|---|
GET |
/openapi/v1/template/tags |
Retrieve filter groups and tags |
GET |
/openapi/v1/template/list |
Filter and paginate templates, including pricing rules |
POST |
/openapi/v1/template/generate |
Generate one video with one template |
GET |
/openapi/v1/videos/{video_id} |
Retrieve generation status and output |
GET |
/openapi/v1/videos?kind=template |
Retrieve template video history |
Integration flow: retrieve tags and templates → display a template and collect inputs → calculate its price → submit generation → poll by video_id. There is currently no template detail endpoint, price quote endpoint, or template generation webhook.
GET /openapi/v1/template/list
Authorization: Bearer <API_KEY>
| Query parameter | Type | Required | Default | Description |
|---|---|---|---|---|
type |
string | No | Any | One template type code, such as bfcm_2026 |
category |
string | No | Any | One product category code |
video_style |
string | No | Any | One video style code |
tag_ids |
string | No | Any | Comma-separated positive integer tag IDs, such as 11,12; OR within a group, AND across groups |
keyword |
string | No | Any | Substring match against the entire display JSON; may match text in any language, URLs, or JSON field names |
page |
integer | No | 1 |
Starts at 1; 0 uses the default and negative values are invalid |
page_size |
integer | No | 20 |
1–100 items per page; 0 uses the default |
Without filters, the endpoint returns a page of all enabled templates. Type, category, and video style are independent fields, not tag groups. Use codes from the current catalog. There is no template_id query parameter.
| type code | Description |
|---|---|
daily |
Everyday product video templates |
bfcm_2026 |
Black Friday / Cyber Monday promotional templates for 2026 |
type filters the template list. Pass one code at a time, such as ?type=daily or ?type=bfcm_2026; omit it to include all types. Types can change with catalog updates, so use templates[].type from the paginated catalog in your environment. A filter with no matches returns templates=[] and total=0. To generate a video, submit the selected template_id; do not include type in the generation request.
export BASE_URL='https://growth-api.pixverse.ai'
export API_KEY='mh_live_REPLACE_WITH_PRODUCTION_API_KEY'
curl --get "$BASE_URL/openapi/v1/template/list" \
--header "Authorization: Bearer $API_KEY" \
--data-urlencode 'type=bfcm_2026' \
--data-urlencode 'page=1' \
--data-urlencode 'page_size=20'
A successful response is 200 OK, with Cache-Control: no-store and X-Request-Id. All IDs, media URLs, and prices below are illustrative, not current inventory or price quotes.
{
"templates": [
{
"id": 202611090001,
"type": "bfcm_2026",
"category": "generic",
"video_style": "ugc_style",
"layout": {
"default": "en",
"name": {"en": "Black Friday Offer", "zh": "黑五优惠"},
"description": {"en": "Present a limited-time product offer.", "zh": "展示商品限时优惠。"},
"cover_url": {"en": "https://media.pixverse.ai/templates/example/cover.jpg", "zh": "https://media.pixverse.ai/templates/example/cover-zh.jpg"},
"video_url": {"en": "https://media.pixverse.ai/templates/example/preview.mp4", "zh": "https://media.pixverse.ai/templates/example/preview-zh.mp4"},
"duration": {"default": 15},
"aspect_ratio": {"default": "9:16", "options": ["9:16", "4:5", "1:1", "16:9"]},
"resolution": {"default": "720p", "options": ["720p", "1080p"]},
"template_params": [
{
"key": "offer_details",
"ui_type": "discount_text_input",
"display_name": {"en": "Deal details", "zh": "优惠信息"},
"required": true,
"max_length": 300,
"placeholder": {"en": "Price, promo code and end date", "zh": "填写价格、优惠码和截止日期"}
}
]
},
"tag_ids": [11],
"pricing": {
"expression": {"if": [{"===": [{"var": "quality"}, "1080p"]}, 1260, 490]},
"fixed_params": {}
}
}
],
"total": 1,
"page": 1,
"page_size": 20,
"request_id": "list-templates-001"
}
| Response field | Type | Description |
|---|---|---|
templates |
array | Enabled templates on this page, ordered by creation time descending, then ID descending; [] when none match |
templates[].id |
integer | The template_id to submit; use the actual numeric value, including 0 if returned |
templates[].type / category / video_style |
string | Classification codes; category and video style may be empty strings |
templates[].layout |
object | Display configuration, described below |
templates[].tag_ids |
integer[] | Visible tag IDs assigned to this template; [] if none |
templates[].pricing |
object / null | Pricing rule and fixed inputs; null means pricing configuration is unavailable, so disable generation for this item |
total |
integer | Total number of matching templates |
page / page_size |
integer | Effective page and page size; fetch subsequent pages to retrieve the full catalog |
request_id |
string | Request tracking ID |
layout is a JSON object whose fields may vary by template. The server does not select a display language. Clients should tolerate additional and optional fields.
| Configuration | Client behavior |
|---|---|
name, description |
Usually {en, zh}; choose en for an English UI or zh for a Chinese UI |
cover_url, video_url |
Usually {en, zh}; select the corresponding cover image and preview video |
duration, aspect_ratio, resolution |
Language-independent {default, options?} values used to display defaults and available choices, and validate the selected specifications |
template_params |
Render the extra inputs in array order; each key maps to the same key in the generation request |
Input declarations contain key, ui_type, and optional display_name, placeholder, required, and max_length. Current UI conventions use text_input for a general multiline text field and discount_text_input for offer text. display_name and placeholder may be strings or multilingual objects. required defaults to false; the UI convention for an omitted max_length is 500 Unicode code points.