通用视频接口 · OpenAI 格式

查询视频

用视频 ID 查询生成进度，成功后返回视频地址。返回结果是 OpenAI 格式的视频对象，另外带有分辨率、价格和视频地址等字段。

GEThttps://your-domain/v1/videos/{id}

请求示例

curl https://your-domain/v1/videos/video_8f3k2m9x4q1w7e5r0t6y2u4p \
  -H "Authorization: Bearer $API_KEY"

返回结果

{
  "id": "video_8f3k2m9x4q1w7e5r0t6y2u4p",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "completed",
  "progress": 100,
  "created_at": 1791691200,
  "completed_at": 1791691318,
  "expires_at": null,
  "seconds": "5",
  "size": "1280x720",
  "prompt": "清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾",
  "remixed_from_video_id": null,
  "error": null,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": false,
  "input_mode": "text",
  "price": "4.968",
  "video_url": "https://your-domain/uploads/videos/2026/10/k3Zq8mVt2LxR9pWa.mp4"
}

请求参数

路径参数

idstring必填

视频 ID，即创建视频返回的 id。账号下的所有视频都可以查询，包括用火山方舟格式创建的任务和在控制台生成的视频。

返回参数

idstring

视频 ID，以 video_ 开头。

objectstring

固定为 video。

modelstring

模型 ID。

statusstring

视频状态：queued、in_progress、completed 或 failed，见视频状态。

progressinteger

进度百分比，0 到 100。部分模型不提供真实进度，这时是按已用时间估算的值，仅供参考。

created_atinteger

创建时间，Unix 时间戳（秒）。

completed_atinteger | null

完成时间，Unix 时间戳（秒），成功之前为 null。

expires_atnull

固定为 null，视频长期保存，不会过期。

secondsstring

视频时长，单位秒。由模型决定时长的任务（auto_duration 为 true）在完成前是冻结费用所按的时长，成功后是视频的实际时长。

sizestring

视频尺寸，例如 1280x720。画幅跟随素材的视频只返回分辨率，例如 720p。

promptstring

提示词。

remixed_from_video_idnull

固定为 null。

errorobject | null

失败原因，只在 status 为 failed 时有值，其他状态为 null。

子字段

codestring

错误码，见失败原因。

messagestring

错误信息。

resolutionstring

分辨率，例如 720p。

aspect_ratiostring

画幅，例如 16:9。画幅跟随首帧、参考素材或原视频时为空字符串。

audioboolean

是否生成声音。

input_modestring

生成方式：text、image、frames、reference、edit 或 extend，见生成方式。

auto_durationboolean

由模型决定时长时为 true，否则不返回。

reference_secondsinteger

参考视频的总时长，单位秒，不足 1 秒的部分不计，用于计费。没有参考视频时不返回。

pricestring

费用，单位元。未完成时是冻结的金额，成功后是实际扣费的金额；失败的视频不扣费，冻结的金额全部退回。

video_urlstring

视频地址，mp4 格式，只在 status 为 completed 时返回。视频转存在本平台，可以长期访问；转存失败时返回模型服务商的原始地址，这种地址可能在 24 小时后失效，建议及时下载。

视频状态

status	说明
`queued`	排队中
`in_progress`	生成中
`completed`	生成成功，video_url 是视频地址，同时完成扣费
`failed`	生成失败、被取消或超时，error 说明原因，冻结的费用全部退回

completed 和 failed 是最终状态。生成时间与模型、分辨率和时长有关，通常需要几分钟，建议每 10 秒以上查询一次。

失败原因

error.code	说明
`content_policy_violation`	提示词、素材或生成的视频未通过审核，message 里有具体原因
`invalid_request`	请求的参数或素材不被模型接受，message 里有具体原因
`generation_failed`	生成过程出错，可以稍后重新提交
`timeout`	超过 12 小时没有完成
`cancelled`	任务被取消（用火山方舟格式或 MiniMax 格式取消了排队中的任务，见火山方舟格式、MiniMax 格式）
`submit_interrupted`	提交过程中断，请重新提交
`upstream_unavailable`、`channels_busy`、`no_available_channel`	提交时模型服务暂时不可用或繁忙，创建接口当时已返回错误，可以稍后重新提交
`aborted`	任务被平台管理员终止，message 里有原因

以上情况都不扣费，冻结的金额全部退回。