接口说明

接口地址

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

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

模型系列

全部视频模型共用本页的异步协议与任务对象,但提交请求体的形状因系列而异(平台原样透传给上游),各系列的输入结构与专属参数见对应系列页:

系列	请求体形状	当前模型
Seedance 系列	方舟风格:`content` 数组 + `--duration`/`--resolution` 指令	`doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`、`doubao-seedance-2-0-mini-260615`
Wan 视频系列	DashScope 风格:`input.prompt`/`input.media` + `parameters`	`wan2.7-t2v`、`wan2.7-i2v`、`wan2.7-r2v`、`wan2.6-t2v`
HappyHorse 系列	DashScope 风格:`input.prompt`/`input.media` + `parameters`	`happyhorse-1.0-t2v`、`happyhorse-1.0-i2v`、`happyhorse-1.0-r2v`、`happyhorse-1.0-video-edit`

提交请求

请求体为 JSON,平台处理的字段如下,其余字段(含 content、input 等输入结构)原样透传给上游,应按所选模型系列的形状填写(见上方"模型系列"):

字段	类型	必填	说明
`model`	string	是	平台没有该模型 → 404 `model_not_found`
`content`	array	视系列	方舟风格系列(Seedance)的输入:`[{"type":"text","text":"<提示词>"}]`;`text` 内可写 `--duration <秒>`、`--resolution <720p\|1080p>` 指令来指定时长与分辨率
`input`	object	视系列	DashScope 风格系列(Wan / HappyHorse)的输入:`prompt`、`media` 等,详见系列页
`parameters.duration`	integer	否	显式指定时长(秒),缺省为 5;参与预扣计算
`parameters.size`	string	否	形如 `"宽*高"`,长边 ≥1440 记为 1080p 计费档,否则记为 720p 档;参与预扣计算
`callback_url`	string	否	任务到达终态时的回调地址;仅接受 `https`,且不能解析到内网/回环/链路本地等非公网地址,否则 → 400 `invalid_request_error`;该字段不会转发给上游

预扣参数的取舍规则: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。

任务对象字段

所有状态都包含:

字段	类型	说明
`task_id`	string	`vt_` 前缀 + UUID
`model`	string	提交时使用的平台模型名
`status`	string	`pending` / `running` / `succeeded` / `failed`
`created_at`	integer	任务创建时间,Unix 秒
`duration`	integer/number	时长(秒);默认为提交时预扣计算出的值,任务结束后如果上游返回了实际时长会被覆盖
`resolution`	string	`720p` / `1080p`;默认为提交时预扣计算出的档位,任务结束后如果上游返回了可识别的分辨率会被覆盖

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

字段	类型	说明
`completed_at`	integer	任务结束时间,Unix 秒
`usage`	object	上游返回的用量信息,视上游而定可能包含 `duration`、`SR`(分辨率短边)、`ratio`(画面比例,如 `"16:9"`)、`completion_tokens`、`total_tokens` 等子字段,缺失的子字段不出现
`ratio`	string	画面比例(如 `"16:9"`),仅上游返回了该信息时出现
`credits_charged`	number	本次实际扣费(credit)

succeeded 额外追加:

字段	类型	说明
`video_url`	string	视频下载直链
`expires_at`	integer	`video_url` 的失效时间,Unix 秒

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

failed 额外追加:

字段	类型	说明
`error`	object	`{"code": "...", "message": "..."}`;`code` 取值 `timeout`(平台侧轮询超时)或 `upstream_error`(上游生成失败,不透出上游原始错误码)

完整示例

# 1. 提交任务
curl https://api.looptoken.cc/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",...}

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

计费

视频生成按“时长 × 分辨率档位单价”计费,单价见模型列表。提交时按解析出的 duration/resolution 预扣,任务结束后按上游实际返回的用量结算,多退少补;credits_charged 为本次实际扣费金额。

错误

状态码	code	触发场景
400	`invalid_request_error`	请求体不是合法 JSON,或 `callback_url` 不是字符串/不满足 https 与公网地址要求
402	`insufficient_credits`	账户余额不足以覆盖预扣费用
404	`model_not_found`	提交时,平台没有该模型
404	`task_not_found`	查询时,`task_id` 不存在或不属于当前账户
502	`upstream_error`	上游提交失败且重试耗尽
503	`no_available_channel`	该模型当前没有可用渠道

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

接口说明

本页内容