接口说明

接口地址

POST /v1/videos/generations
GET  /v1/tasks/{task_id}

视频生成耗时较长(通常数十秒到数分钟),接口采用平台自定义的异步两步协议,不是 OpenAI 官方接口:提交请求立即返回 202 和一个任务对象,之后用任务对象里的 task_id 轮询查询接口,直到任务进入终态(succeeded 或 failed)。建议轮询间隔 5-10 秒。

模型系列

全部视频模型共用本页的异步协议与任务对象,但提交请求体的形状和参数规则因系列而异,各系列的输入结构与专属参数见对应系列页:

提交请求

请求体为 JSON。model 和 callback_url 是公共字段；生成输入与控制字段必须按所选模型系列填写，不能把一个系列的参数规则套用到另一个系列。

主流模型扁平字段

主流视频模型使用顶层扁平字段：prompt、duration、resolution、mode、audio、aspect_ratio、image_urls、first_frame_image。平台会按所选主流模型解析这些字段，而不是把它们视为未处理的附加字段。

主流模型的预扣计费只读取模型默认值和顶层 duration / resolution / mode / audio。content 中的旧式文本指令以及 parameters 中的嵌套字段不参与主流模型的时长或质量档位计算；未传对应顶层字段时直接使用该模型默认值。各模型默认值、有效时长、分辨率和专属字段见主流视频模型。aspect_ratio、image_urls 与 first_frame_image 作为生成输入按模型能力处理，不参与时长或质量档位的默认值计算。

字段必须符合具体模型的能力范围。例如 kling-v3 使用 mode 选择质量档位，不接受顶层 resolution。

其他系列字段

对于这些系列,预扣参数的取舍规则是:content 里的 --duration/--resolution 指令与 parameters.duration/parameters.size 整体二选一——请求体中只要出现 parameters 键,平台就只从 parameters 内读取 duration/size,text 里的指令会被整体忽略(不做字段级回退,parameters 中缺失的子字段按默认值 5 秒 / 720p 处理)。例如 parameters 只传了 {"duration": 10}、同时 text 里写了 --resolution 1080p,实际按 10 秒 / 720p 计。注意平台预扣不识别 parameters.resolution(Wan/HappyHorse 的档位写法),该写法下预扣按 720p 档。这份参数只用于提交时的预扣费计算,任务结束后按实际结果多退少补(参见下文"任务对象字段"中终态 duration/resolution 的覆盖规则)。

提交成功返回 202,响应体为任务对象(见下文,此时处于 pending 状态)。

查询任务

用提交返回的 task_id(格式 vt_ 前缀 + UUID)调用 GET /v1/tasks/{task_id} 查询当前状态。任务不存在、或不属于当前 API Key 所在账户 → 404 task_not_found。

轮询时用 status 判断是否结束,progress 只用来展示进度条。只有部分模型的上游会回报真实进度,其余模型在整个生成过程中都是 0,直到终态跳到 100——不要用 progress 是否变化来判断任务是否卡住。当前会回报真实进度的是 seedance-2-0-exl、seedance-2-5-exl、seedance-2-5-exr、seedance-2-5-max、seedance-2-5-ak、seedance-2-0-ak、seedance-2-5-hig、seedance-2-0-hig、seedance-2-0-mag、seedance-2-0-exr。

任务对象字段

所有状态都包含:

进入终态(succeeded/failed)后追加:

succeeded 额外追加:

video_url 有时效,过期后字段不再返回(链接本身也会失效):有效期上限为任务完成后 72 小时,具体时长取决于平台内部转存状态,某些情况下会短至完成后 24 小时。请在拿到 succeeded 结果后尽快下载转存,不要缓存链接长期使用。

failed 额外追加:

完整示例

# 1. 提交任务
curl https://api.vibelab.me/v1/videos/generations \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [{"type": "text", "text": "海边日落,海浪拍打礁石 --duration 5 --resolution 720p"}]
  }'
# => 202 {"task_id":"vt_...","status":"pending","progress":0,...}

# 2. 用返回的 task_id 轮询,间隔建议 5-10 秒
curl https://api.vibelab.me/v1/tasks/vt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY"

计费

视频模型的计费方式因模型而异：部分模型按秒计费，部分模型按单次任务固定价格计费，具体金额还可能取决于分辨率或质量档位。提交时先按请求参数预扣，任务结束后按实际结果结算，多退少补；credits_charged 为本次实际扣费金额。最终价格以定价页为准。

错误

完整错误响应体格式与更多错误码见错误码。