Growth Studio OpenAPI接入文档 · Video Status and Results
统一视频查询用于查看生成视频和导入素材。爆款复刻的 run_id 使用爆款复刻(查询复刻任务);商品套图的 task_id 使用商品套图(查询商品套图结果)。
| status | 是否终态 | 说明 |
|---|---|---|
queued |
否 | 已进入队列,等待执行 |
processing |
否 | 正在生成 |
succeeded |
是 | 生成成功,可以读取 output.video_url |
failed |
是 | 生成失败,读取 error |
canceled |
是 | 任务已取消,读取 error |
资源级错误:
| error.code | retryable | 说明 |
|---|---|---|
GENERATION_FAILED |
true | 视频生成失败,可以根据业务需要重新创建任务 |
GENERATION_CANCELED |
false | 视频生成任务已取消 |
请求
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'
成功生成响应
HTTP 状态码:200 OK
{
"video_id": "627410861853514292",
"status": "succeeded",
"kind": "product",
"product": {
"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,
"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"
}
主要响应字段:
| 字段 | 类型 | 说明 |
|---|---|---|
video_id |
string | 视频 ID |
kind |
string | 视频类型:product、hook、creation、template、variation、uploaded |
status |
string | 视频状态 |
product.title |
string | 创建任务时提交的商品标题 |
settings |
object | 实际保存的视频生成配置 |
output |
object/null | 生成成功时返回视频结果,否则为 null |
output.video_url |
string | MP4 视频下载地址 |
output.thumbnail_url |
string | 视频首帧地址,尚未生成时可能为空字符串 |
output.mime_type |
string | 当前为 video/mp4 |
price |
integer | 创建时记录的折前原价,单位为美分。免费额度、折扣及退款不会改变该值;实际扣款请查询钱包流水 |
currency |
string | 视频生成币种,本地区为 USD;上传素材的该字段为空字符串 |
ledger_source_id |
string | 生成扣款的关联标识,用于匹配钱包流水的 source_id;上传素材为空字符串 |
ledger_source_type |
string | 生成扣款的来源类型,用于匹配钱包流水的 source_type,通常为 video 或 video_batch;上传素材为空字符串 |
metadata |
object | 创建任务时传入的 metadata |
error |
object/null | 视频失败或取消时的资源级错误 |
supports_edit |
boolean | 是否可编辑 |
edit |
object | |
edit.mode |
string | 当前固定为 replace_clip |
edit.status |
string | 最近一次编辑的状态 |
edit.latest |
object | 最近一次编辑的任务信息;尚未提交过编辑时省略 |
edit.latest.id |
string | 编辑任务ID |
edit.latest.status |
string | 最近一次编辑的状态;与 edit.status 一致 |
edit.latest.clip_index |
integer | 最近一次编辑的片段序号 |
edit.latest.instruction |
string | 最近一次提交的编辑说明 |
created_at |
string | 创建时间,UTC |
updated_at |
string | 最近更新时间,UTC |
request_id |
string | 本次查询请求的追踪标识 |
template_id |
integer | 仅模板视频(kind=template)返回,合法 ID 可以为 0 |
source_video_id |
string | 仅裂变视频(kind=variation)返回,对应创建时引用的源视频 |
商品、模板、裂变和专业创作视频共用此详情接口,但 settings 的字段会随视频类型变化:
| 视频类型 | settings 补充规则 |
|---|---|
模板视频 template |
回显实际规格、language、voiceover、captions、background_music 与人物模式 |
裂变视频 variation |
回显实际规格、目标 language、voiceover、captions;不返回商品人物模式和背景音乐配置 |
生成中响应
状态为 queued 或 processing 时,HTTP 状态仍为 200,并返回: