两步式异步流程
- 提交：POST /v1/videos 立即返回 id 和 submitted 状态，此时不扣费。
- 轮询：每隔几秒请求 GET /v1/videos/{id}，直到状态变为 succeeded 或 failed。
首次获取成功结果时，系统按上游实际时长和单价扣费。扣费是幂等的，重复轮询不会重复扣款；失败或超时不扣费。视频 URL 通常为约 24 小时有效的临时链接，请及时下载。
提交参数
Body 参数application/json
modelstring必填视频模型，可在下方查看可用模型。
示例：
your-video-model-idpromptstring必填需要生成的画面描述。
示例：
一只柴犬在草地上奔跑，电影质感imagestring | string[]可选单张参考图。支持公网 URL 或 data URI；也兼容 string[]，但多图建议使用 images。
示例：
https://.../reference.pngimagesstring[]可选多张参考图，按数组顺序编号为图片1、图片2……；支持公网 URL 或 data URI。
示例：
["https://.../person.png","https://.../scene.png"]first_framestring可选首帧关键帧 URL，用于首帧生视频或首尾帧补间。
示例：
https://.../first.pnglast_framestring可选尾帧关键帧 URL；通常与 first_frame 一起使用。
示例：
https://.../last.pngreference_videostring | string[]可选参考视频 URL 或 URL 数组，仅在支持多模态参考的模型上生效。
示例：
https://.../motion.mp4reference_audiostring | string[]可选参考音频 URL 或 URL 数组；不能单独使用，必须同时提供参考图片或视频。
示例：
https://.../voice.mp3durationinteger可选视频时长（秒），支持范围由具体模型决定。
示例：
5resolutionstring可选输出分辨率，例如 720P 或 1080P。
示例：
720Paspect_ratiostring可选画面比例，例如 16:9、9:16 或 1:1。
示例：
16:9enable_audioboolean可选是否生成音频。默认开启——不传即按 true 处理，传 false 才关闭。兼容别名 generate_audio（两者都传时以 enable_audio 为准）。实际是否有声还取决于所选模型是否支持音频生成。
示例：
true图生视频与多参考图（本站统一格式）
单张参考图使用 image，多张参考图使用 images。提示词中可按数组顺序写“图片1”“图片2”来绑定人物、服装、场景等用途。首尾帧请使用 first_frame 和 last_frame，不要把火山原生 content 数组直接放进本站 /v1/videos。
单张参考图 · 图生视频
curl https://zerofa.ai/v1/videos \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-video-model-id",
"prompt": "让画面中的人物转身走向窗边，镜头缓慢推进",
"image": "https://example.com/first-frame.png",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9"
}'多张参考图 · 参考生视频
curl https://zerofa.ai/v1/videos \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-video-model-id",
"prompt": "人物外观参考图片1，服装参考图片2，场景参考图片3，生成电影感追逐镜头",
"images": [
"https://example.com/person.png",
"https://example.com/outfit.png",
"data:image/png;base64,..."
],
"duration": 5,
"resolution": "1080P",
"aspect_ratio": "16:9",
"enable_audio": true
}'参考图数量、文件大小、可用角色和是否支持参考视频/音频由所选模型决定。本站统一接口不接收逐图 role；首尾帧使用专用字段，其他厂商专属 role 请改用对应原生透传入口并查阅厂商官方文档。
查询任务
GET
/v1/videos/{id}返回 submitted、running、succeeded 或 failed 状态。成功时包含 urls 和 duration_sec。终态结果会缓存，重复查询不会再次请求上游。
可用模型
加载中…
视频模型见 模型广场 并筛选视频类型。费用按时长（秒）乘以模型单价计算。
请求与响应体
用下面的示例确认请求格式与返回结构。需要在线发起请求时，点击页面顶部“调试”拉起在线运行面板。
① 提交
curl https://zerofa.ai/v1/videos \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-video-model-id",
"prompt": "一只柴犬在草地上奔跑，电影质感",
"duration": 5,
"resolution": "720P",
"aspect_ratio": "16:9",
"enable_audio": true
}'
# → {"id":"<task-id>","status":"submitted"}② 轮询
curl https://zerofa.ai/v1/videos/<task-id> \
-H "Authorization: Bearer sk-zerofa-xxx"
# running → {"id":"...","status":"running","progress":40}
# succeeded → {"id":"...","status":"succeeded",
# "urls":["https://..."],"duration_sec":5}