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.
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.
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.