Growth Studio OpenAPI Integration Guide · 视频状态与结果查询

Video IDs use the unified queries below. Query a viral clone run_id through Viral Clone, and a product image suite task_id through Product Image Suites.

Video Status and Results (Video Status) · Video Status and Results (Get Video Details) · Video Status and Results (List Videos) · Video Status and Results (Polling Recommendations)

Video Status

The top-level status represents the state of the original video generation task:

status Terminal Description
queued No Entered the queue, waiting for execution
processing No Generating
succeeded Yes Generated successfully, can read output.video_url
failed Yes Generation failed; read error
canceled Yes Task canceled, read error

edit.status is only returned on videos that support editing, indicating the status of the latest clip replacement task. Editing will not change the top-level status; after the video has been successfully generated, the top-level status will remain succeeded.

edit.status Terminal Description
not_started Yes No edit has been initiated; the first edit can be submitted when supports_edit=true
queued No The editing task has entered the queue and new edits cannot be submitted yet
processing No The editing task is being generated and new edits cannot be submitted yet
succeeded Yes The latest edit succeeded; output.video_url has been updated to the latest final video
failed Yes The latest edit failed; the current output.video_url still points to the last available final video
canceled Yes The latest edit was canceled; the current output.video_url still points to the last available final video

Resource-level errors:

error.code retryable Description
GENERATION_FAILED true Video generation failed, the task can be re-created according to business needs
GENERATION_CANCELED false Video generation task canceled

Get Video Details

Request

GET /openapi/v1/videos/{video_id}
Authorization: Bearer <API_KEY>

cURL

curl --request GET \
  "${BASE_URL}/openapi/v1/videos/627410861853514292" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header 'Accept: application/json'

Successful Generation Response

HTTP status code: 200 OK

{
  "video_id": "627410861853514292",
  "status": "succeeded",
  "product": {
    "source_url": "https://shop.example.com/products/running-shoes",
    "title": "Lightweight Running Shoes"
  },
  "settings": {
    "aspect_ratio": "9:16",
    "duration_seconds": 30,
    "resolution": "1080p",
    "language": "en-US",
    "voiceover": true,
    "captions": true,
    "background_music": true,
    "avatar_mode": "auto"
  },
  "output": {
    "video_url": "https://media.pixverse.ai/videos/result.mp4",
    "thumbnail_url": "https://media.pixverse.ai/videos/result.webp",
    "mime_type": "video/mp4"
  },
  "price": 2000,
  "currency": "USD",
  "metadata": {
    "order_id": "order_123456",
    "campaign_id": "campaign_001"
  },
  "error": null,
  "supports_edit": true,
  "edit": {
    "mode": "replace_clip",
    "status": "not_started"
  },
  "created_at": "2026-07-22T08:00:00Z",
  "updated_at": "2026-07-22T08:03:00Z",
  "request_id": "get-video-001",
  "ledger_source_id": "627410861853514292",
  "ledger_source_type": "video"
}

Main response fields:

Field Type Description
video_id string Video ID
kind string Video category; template-generated videos return template
template_id integer Present for kind=template; actual catalog template ID
status string Video status
product.source_url string The URL of the product details page submitted when creating the task; omit if not passed
product.title string Product title submitted when creating the task or fetched from the product page
settings object Actual saved video generation configuration
output object/null Video output when generation succeeds; otherwise null
output.video_url string MP4 video download URL
output.thumbnail_url string URL of the video's first frame; may be an empty string if it has not yet been generated
output.mime_type string Currently video/mp4
price integer The pre-discount price recorded at creation, in integer USD cents. Free allowances, discounts, and refunds do not change this value. Use wallet transactions for the actual charge
currency string Video generation currency; USD in the international environment. Uploaded assets have an empty currency
ledger_source_id string Identifier used to match the generation charge against wallet transaction source_id; empty for uploaded assets
ledger_source_type string Match against wallet transaction source_type, typically video or video_batch; empty for uploaded assets
metadata object Metadata provided when the task was created
error object/null Resource-level error when video fails or is canceled
supports_edit boolean Whether the video uses the new Agent workflow and has a complete, persisted set of editable clip outputs. This is a capability flag and does not guarantee that an edit can be submitted immediately. It is false for legacy workflows, incomplete generation, or incomplete outputs
edit object Returned only for new Agent videos whose complete clip outputs have been persisted by the server; omitted for legacy videos
edit.mode string Currently fixed to replace_clip
edit.status string not_started, queued, processing, succeeded, failed or canceled; indicates the status of the latest edit
edit.latest object Information about the latest edit task; omitted if no edit has been submitted
edit.latest.id string Edit task ID
edit.latest.status string The status of the last edit; consistent with edit.status
edit.latest.clip_index integer Clip index of the latest edit
edit.latest.instruction string Edit instruction from the latest submission
created_at string Creation time, UTC
updated_at string Last updated time, UTC
request_id string The tracking ID of this query request