Growth Studio OpenAPI Integration Guide · 商品视频

Request

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.

cURL

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"
    }
  }'

Product Parameters

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:

Image URL rules: