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,并返回: