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)
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 /openapi/v1/videos/{video_id}
Authorization: Bearer <API_KEY>
curl --request GET \
"${BASE_URL}/openapi/v1/videos/627410861853514292" \
--header "Authorization: Bearer ${API_KEY}" \
--header 'Accept: application/json'
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 |