先选择请求形态
统一端点覆盖常见视频生成场景。先按素材形态选择字段，再确认所选模型是否支持对应能力。
| 目标 | 关键字段 | 适用场景 |
|---|---|---|
| 文生视频 | model + prompt | 仅使用提示词生成 |
| 单图生视频 | image | 让一张图片动起来 |
| 多参考图 | images[] | 分别约束人物、服装或场景 |
| 首尾帧补间 | first_frame + last_frame | 明确指定开始和结束画面 |
| 视频编辑 | video + images[] | 按文字指令替换元素或转换风格 |
| new-api 兼容调用 | seconds + size + images | 沿用 new-api 客户端字段 |
表中均为用户侧统一接口。如果必须保留厂商原生 content、role 或新发布参数，请使用对应原生透传入口，并以厂商官方文档为字段准则。
两步式异步流程
- 提交：POST /v1/videos 立即返回 id 和 queued 状态。
- 轮询：每隔几秒请求 GET /v1/videos/{id}，直到状态变为 completed 或 failed。
- 下载：任务 completed 后，请求 GET /v1/videos/{id}/content 获取成品。
API Key 调用会在提交时预留预计费用，成功后按实际结果结算；失败或超时会释放预留。结算和释放均为幂等操作，重复轮询不会重复扣款。
提交参数
Header 参数
Authorizationstring必填API Key，格式为 Bearer <key>。
示例：
Bearer sk-zerofa-xxxContent-Typestring必填示例：
application/jsonBody 参数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.pngvideostring可选视频编辑的源视频公网 URL。提供后会自动使用 video_edit 模式；兼容别名 video_url。
示例：
https://.../source.mp4reference_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:9bitrate_modestring可选Seedance 输出码率模式，仅支持 standard（标准码率）和 high（高码率）；不传时优先使用模型默认值，模型未配置时使用上游默认值。
示例：
standardnegative_promptstring可选不希望出现在结果中的内容；仅支持该能力的模型会生效。
示例：
模糊，抖动，文字水印seedinteger可选随机种子。固定种子有助于复现实验，但跨模型或上游版本不保证完全一致。
示例：
123456enable_audioboolean可选是否生成音频。默认开启——不传即按 true 处理，传 false 才关闭。兼容别名 generate_audio（两者都传时以 enable_audio 为准）。实际是否有声还取决于所选模型是否支持音频生成。
示例：
trueaudio_settingstring可选视频编辑的声音策略：auto 由模型处理，origin 保留源视频原声。
示例：
origin图生视频与多参考图（本站统一格式）
单张参考图使用 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 请改用对应原生透传入口并查阅厂商官方文档。
HappyHorse 视频编辑
happyhorse-1.0-video-edit 接收 1 个源视频和最多 5 张参考图，通过自然语言完成局部替换或整体风格转换。
源视频 + 参考图 · 视频编辑
curl https://zerofa.ai/v1/videos \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "happyhorse-1.0-video-edit",
"prompt": "把视频中人物的外套替换成图片1中的条纹外套，保留原动作和镜头",
"video": "https://example.com/source.mp4",
"images": ["https://example.com/striped-coat.png"],
"resolution": "1080P",
"audio_setting": "origin",
"seed": 123456
}'源视频必须是公网可访问的 MP4/MOV URL。输出时长由源视频决定（最多取前 15 秒），因此 duration 和 aspect_ratio 不会发送给该模型。任务成功后按百炼返回的实际 usage.duration 结算。
new-api 兼容的用户侧请求
用户也可以直接按 new-api 的通用视频任务结构调用本站同一个 /v1/videos 端点，无需经过另一套网关。model、prompt、image、images 和 mode 可直接使用；以下别名会归一化到本站统一任务。
用户直调本站 · new-api 格式
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中的场景，生成电影感镜头",
"seconds": "5",
"size": "1920x1080",
"images": [
"https://example.com/person.png",
"https://example.com/location.png"
],
"metadata": {
"client_job_id": "order-20260809-001"
}
}'兼容字段
secondsinteger | string可选视频时长，支持正整数或数字字符串；与 duration 同义，seconds 优先。
示例：
5sizestring可选输出尺寸，使用 WxH 格式；系统据此识别分辨率档位和画面比例。
示例：
1920x1080input_referencestring | object可选单张参考图，可传 URL/data URI 字符串，或包含 image_url 的对象。
示例：
https://.../reference.pngmetadataobject | JSON string可选调用方自定义业务元数据，支持 JSON 对象或编码后的 JSON 字符串；任务查询时原样返回。
示例：
{"client_job_id":"order-001"}metadata 用于保存业务元数据，不代替生成参数。用户直调本站时，尺寸请用 size 或顶层 resolution/aspect_ratio，音频请用顶层 enable_audio/generate_audio；火山原生 content/role 请走 /ark 并以官方文档为准。
查询任务
GET
/v1/videos/{id}查询返回 OpenAI Videos 兼容对象。状态固定为 queued、in_progress、completed 或 failed；终态结果会缓存，重复查询不会再次请求上游。progress 是阶段指示值，不是上游逐帧进度。
| status | progress | 含义 |
|---|---|---|
| queued | 0 | 任务已接收，等待上游处理。 |
| in_progress | 50 | 上游正在生成或平台正在处理成品。 |
| completed | 100 | 任务完成；metadata.url 为兼容扩展，也可通过 content 端点下载。 |
| failed | 100 | 任务失败；响应 error.message 包含可公开的失败原因。 |
下载成品
GET
/v1/videos/{id}/contentcontent 端点会以 307 重定向到当前可用的成品地址。客户端应允许重定向，并继续携带本站请求所需的 Authorization。
③ 下载
curl -L https://zerofa.ai/v1/videos/<task-id>/content \
-H "Authorization: Bearer sk-zerofa-xxx" \
--output result.mp4建议业务端以 content 端点为稳定入口，不要持久依赖 metadata.url 的域名或查询参数。实际媒体地址通常是短期签名 URL，需要长期保存时请及时下载到自己的存储。
可用模型
加载中…
视频模型见 模型广场 并筛选视频类型。费用按时长（秒）乘以模型单价计算。
请求与响应体
用下面的示例确认请求格式与返回结构。需要在线发起请求时，点击页面顶部“调试”拉起在线运行面板。
① 提交
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>","object":"video","status":"queued",
# "progress":0,"seconds":"5","size":"1280x720"}② 轮询
curl https://zerofa.ai/v1/videos/<task-id> \
-H "Authorization: Bearer sk-zerofa-xxx"
# queued → {"id":"...","status":"queued","progress":0}
# in_progress → {"id":"...","status":"in_progress","progress":50}
# completed → {"id":"...","status":"completed","progress":100,
# "metadata":{"url":"https://.../result.mp4"}}