Growth Studio OpenAPI Integration Guide · 旧模板接口(已弃用)

This chapter preserves the old integration contract. New integrations should use Template Creation. Legacy responses include Deprecation: true and a Link to the replacement endpoint. The localized layout, fixed price_per_video, and request format below apply only to the legacy APIs.

Retrieve the catalog, select a template, then submit product information and runtime options. Save the returned video_id and follow Video Status and Results to retrieve the result.

List Legacy Templates

Templates define fixed generation specifications. Use an id from the current catalog when creating a video.

GET /openapi/v1/video-templates
Authorization: Bearer <API_KEY>
curl --request GET \
  "${BASE_URL}/openapi/v1/video-templates" \
  --header "Authorization: Bearer ${API_KEY}"

The following IDs and media URLs illustrate the response shape; replace them with current catalog values.

{
  "templates": [
    {
      "id": 1,
      "layout": {
        "name": "Product Detail Showcase",
        "description": "Shows the product details and how it is used.",
        "cover_url": "https://media.pixverse.ai/templates/1/cover.jpg",
        "video_url": "https://media.pixverse.ai/templates/1/preview.mp4",
        "aspect_ratio": "1:1",
        "duration": 10,
        "resolution": "720p"
      },
      "price_per_video": 3000
    }
  ],
  "request_id": "list-templates-001"
}
Field Type Description
templates array All enabled templates ordered by ascending id; [] if none are enabled
templates[].id integer Creation template_id; 0 can be a valid ID
templates[].layout object Display name, description, cover, preview, and specifications; fields depend on the current catalog
templates[].price_per_video integer Credits in milli_credit: 1,000 milli-credits equal 1 credit
request_id string Request tracking ID

layout is localized by deployment region: English internationally and Chinese in CN, without nested en or zh objects. Missing fields may be omitted; explicit empty strings, null, and arrays retain their types. Different templates can expose different display fields.

The root has no config, catalog version, currency, or price conversion fields. price_per_video is neither CNY fen nor USD cents. Use wallet transactions for actual charges. An unavailable catalog returns retryable 503 TEMPLATE_CATALOG_UNAVAILABLE.

Generate with a Legacy Template

Each request creates one video for one product using one template. The template determines model, duration, resolution, aspect ratio, and generation price.

POST /openapi/v1/template/videos/generations
Authorization: Bearer <API_KEY>
Content-Type: application/json

This example supplies product information manually, without a product page URL. Replace the template ID and product image with real catalog and platform CDN values.

curl --request POST \
  "${BASE_URL}/openapi/v1/template/videos/generations" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "template_id": 1,
    "product": {
      "title": "Linen shirt",
      "description": "A lightweight, breathable linen shirt for everyday comfort.",
      "brand": "Example",
      "images": [
        {"url": "https://media.pixverse.ai/marketing_hub_website/upload/shirt.png"}
      ]
    },
    "video": {
      "language": "en-US",
      "voiceover": true,
      "captions": false,
      "callout_text_switch": true,
      "background_music": true
    }
  }'
Field Type Required Description
template_id integer Yes ID from the legacy catalog; use 0 if it is a valid catalog ID
product object Yes Manual product information or a product page URL
product.title string For manual input Up to 255 characters
product.images array For manual input 1–10 entries, each {"url":"platform CDN URL"}
product.description string No Up to 5,120 characters
product.brand string No Up to 255 characters
product.price object No Display price with nonempty amount string and three-letter currency; unrelated to generation charges
product.source_url string No HTTP(S) product page URL, up to 2,048 characters; fills information not supplied manually
video object Yes Runtime options
video.language string Yes Full code from ‣ (Target Languages)
video.voiceover boolean Yes Explicit true or false
video.captions boolean Yes Explicit true or false
video.background_music boolean Yes Explicit true or false
video.callout_text_switch boolean No On-screen text; omitted or null means off, independently of captions
video.avatar_url string No Platform CDN avatar image; omitted or empty means no avatar asset, without automatic selection

voiceover, captions, and background_music must be present. false is valid; omission and null are not equivalent to false. The optional callout_text_switch accepts a JSON boolean, not strings or integers 1 / 2. It is independent of captions, as shown in the example. Video detail and list responses do not echo it, so save the submitted value if needed.

Manual product and avatar images must use valid platform CDN URLs from Images and System Avatars or existing platform assets. External image URLs, object_key, and avatar_id are not accepted. Images fetched through product.source_url are processed by the server; manually supplied images still follow these rules.