接口说明

视频生成耗时通常数十秒到数分钟，接口采用平台自定义的异步两步协议，不是 OpenAI 官方接口。本页是所有使用 /v1 的视频模型的公共协议，各模型页只写差异。

快速开始

请求头：Authorization: Bearer $LOOPTOKEN_API_KEY、Content-Type: application/json。请求体上限 10 MiB（不是素材文件大小限制）。

# 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"

模式选择

模型系列

使用 /v1 的视频模型共用本页的异步协议与任务对象，但提交请求体的形状和参数规则因系列而异。不能把一个系列的参数规则套用到另一个系列。

选型对照

本表只列非 Seedance 系列的模型，Seedance 见Seedance 系列。

请求参数

请求体为 JSON。model 和 callback_url 是公共字段；生成输入与控制字段必须按所选模型系列填写。

提交成功返回 202，响应体为任务对象（此时处于 pending 状态）。

主流模型扁平字段

主流视频模型使用顶层扁平字段：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 作为生成输入按模型能力处理，不参与时长或质量档位的默认值计算。

其他系列字段

这些系列的预扣参数取舍规则：

• content 里的 --duration/--resolution 指令与 parameters.duration/parameters.size 整体二选一。
• 请求体中只要出现 parameters 键，平台就只从 parameters 内读取 duration/size/resolution，text 里的指令整体忽略（不做字段级回退）。parameters 中缺失的子字段按默认值 5 秒 / 720p 处理。
• 例：parameters 只传 {"duration": 10}、text 里写了 --resolution 1080p，实际按 10 秒 / 720p 计。
• parameters.resolution 识别 480P/720P/1080P（不区分大小写）；其他取值按 720p 档预扣。
• 这份参数只用于提交时的预扣费计算，任务结束后按实际结果多退少补（终态 duration/resolution 的覆盖规则见下文任务对象字段）。

响应

提交成功返回 202 和任务对象（见下文任务对象字段）。取结果用提交返回的 task_id 查询。

查询任务

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

任务状态

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

任务对象字段

所有状态都包含：

进入终态（succeeded/failed）后追加：

succeeded 额外追加：

failed 额外追加：

回调

提交时可传 callback_url，任务到达终态时由 LoopToken 投递。

• 仅接受 https，且不能解析到内网/回环/链路本地等非公网地址，否则 → 400 invalid_request_error。
• 回调地址不得包含凭据，也不要在其中携带长期密钥。
• 回调内容与任务查询结果保持一致。
• 即使使用回调，也必须保留任务查询作为兜底，回调投递不能替代轮询。
• 不要提交 webhook 或供应商回调字段，统一使用 callback_url。

计费

视频模型的计费方式因模型而异：部分按秒计费，部分按单次任务固定价格计费，具体金额还可能取决于分辨率或质量档位。

• 提交时先按请求参数预扣，任务结束后按实际结果结算，多退少补。
• credits_charged 为本次实际扣费金额。
• 提交同步失败会释放预扣；异步生成失败会退回预扣，失败任务不收取最终生成费用。
• 最终价格以定价页为准，实时价格见模型列表。

错误

上游对该次请求返回 400 且没有更多候选渠道时，平台按上游的 400 回复（code 取上游公开错误码，缺省 invalid_request_error），不会包装成 502。

参数或素材类问题不保证在提交阶段发现，也可能在 202 之后表现为异步 failed。客户端必须同时处理同步 HTTP 错误和异步任务错误，不要解析失败文案编写业务逻辑，按 HTTP 状态、error.code 和任务状态分支处理。响应头 X-Request-Id 可用于问题排查。完整错误响应体格式与更多错误码见错误码。

注意事项

• 只有 seedance-2-5-max、seedance-2-5-hig、seedance-2-0-hig 回报真实 progress → 其余模型生成中恒为 0，用 status 判断是否结束。
• 请求体 parameters 键存在 → 方舟风格系列的预扣只读 parameters，content 里的 --duration/--resolution 整体忽略。
• 使用 callback_url → 仍须保留轮询兜底。
• video_url → 任务完成后尽快转存，不要长期缓存链接。