Growth Studio OpenAPI Integration Guide · 商品视频
POST /openapi/v1/videos
Content-Type: application/json
Authorization: Bearer <API_KEY>
Video creation is asynchronous. A 202 Accepted response means the task was created and entered the processing pipeline; it does not mean the video has finished generating.
The simplest option is to provide only the product detail page URL. Before creating the video, the server fetches the product title, description, brand, price, and images:
curl --request POST \
"${BASE_URL}/openapi/v1/videos" \
--header "Authorization: Bearer ${API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
"product": {
"source_url": "https://shop.example.com/products/running-shoes"
},
"video": {
"aspect_ratio": "9:16",
"duration_seconds": 30,
"resolution": "1080p",
"language": "en-US",
"voiceover": true,
"captions": true,
"background_music": true,
"avatar": {
"mode": "auto"
}
}
}'
You can also provide product information manually. Replace product.images[].url with the actual URL returned by the image upload endpoint:
curl --request POST \
"${BASE_URL}/openapi/v1/videos" \
--header "Authorization: Bearer ${API_KEY}" \
--header 'Content-Type: application/json' \
--data-raw '{
"product": {
"title": "Lightweight Running Shoes",
"description": "Breathable running shoes suitable for daily training.",
"brand": "Example Brand",
"price": {
"amount": "89.99",
"currency": "USD"
},
"images": [
{
"url": "https://media.pixverse.ai/marketing_hub_website/openapi_video_inputs/uploads/22/11/product.webp"
}
]
},
"video": {
"aspect_ratio": "9:16",
"duration_seconds": 30,
"resolution": "1080p",
"language": "en-US",
"voiceover": true,
"captions": true,
"background_music": true,
"avatar": {
"mode": "auto"
}
},
"metadata": {
"order_id": "order_123456",
"campaign_id": "campaign_001"
}
}'
| Field | Type | Required | Description |
|---|---|---|---|
product |
object | Yes | Product information |
product.source_url |
string | No | HTTP/HTTPS URL of the product detail page; when provided, the server fetches product information first; maximum 2,048 characters |
product.title |
string | Conditionally required | Required when product.source_url is omitted; maximum 255 characters |
product.description |
string | No | Product description; maximum 5,120 characters |
product.brand |
string | No | Brand; maximum 255 characters |
product.price |
object | No | Product display price, not video generation fee |
product.price.amount |
string | Conditionally required | Required when price is provided; for example, 89.99 |
product.price.currency |
string | Conditionally required | Required when price is provided; a three-letter currency code such as USD |
product.images |
array | Conditionally required | At least one image is required when product.source_url is omitted; maximum 6 images, with the first used as the primary image |
product.images[].url |
string | Yes | Complete internal CDN URL returned by the image upload endpoint |
Product URL fetching rules:
product.source_url should point to a publicly accessible e-commerce product details page.title, description, brand, price, or images values take precedence; fetched data fills only missing fields.product.source_url is present.Image URL rules:
POST /openapi/v1/image/upload.