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.

List Templates

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.

Currently Supported type Values

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

Display Templates and Collect Inputs

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.