请求链路
调用方只访问 new-api 的 /v1/videos。模型路由、协议转换、上游任务提交和轮询分别由 new-api 与 ZeroFA 完成。
完整链路
调用方
POST https://your-new-api.example.com/v1/videos
↓
new-api（DoubaoVideo 转换）
POST https://zerofa.ai/ark/api/v3/contents/generations/tasks
↓
ZeroFA（Ark 透传并注入火山凭据）
POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks调用方使用 new-api 签发的 Token；new-api 渠道内部填写 ZeroFA 签发的 API Key。两把 Key 不要混用。
配置 DoubaoVideo 渠道
在 new-api 新建火山视频渠道，使用 DoubaoVideo 兼容协议，并把 ZeroFA 作为该渠道的上游。
new-api 渠道配置
渠道类型: DoubaoVideo
Base URL: https://zerofa.ai/ark
API Key: sk-zerofa-xxx
模型: your-seedance-model-id必填配置
DoubaoVideo渠道类型必填选择 DoubaoVideo（豆包视频），由 new-api 把 /v1/videos 请求转换为火山 Ark 任务格式。
https://zerofa.ai/arkBase URL必填只填写到 ZeroFA 的 /ark 根地址，不要附加 /api/v3 或完整任务路径。
sk-zerofa-xxxAPI Key必填填写 ZeroFA 开发者中心签发的 API Key，仅供 new-api 调用 ZeroFA。
your-seedance-model-id模型必填在渠道模型列表和调用 Token 的模型权限中启用本站实际配置的同名 Seedance 模型；不要复制其他站点的模型 ID。
当前 DoubaoVideo 适配器会在 Base URL 后固定追加 /api/v3/contents/generations/tasks，因此 Base URL 必须填写本站后台配置的 API 对外地址并追加 /ark。
① 通过 new-api 提交生成
请求发送到对方 new-api 的域名，并使用对方 new-api 签发的 Token。以下示例为文生视频。
提交视频任务
NEW_API_BASE="https://your-new-api.example.com"
NEW_API_KEY="sk-new-api-xxx"
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "一只柴犬在雪地中奔跑，电影级运镜，画面真实自然",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}
}'
# {"id":"task_xxx","task_id":"task_xxx","object":"video",
# "model":"your-seedance-model-id","status":"queued","progress":0}Body 参数
modelstring必填new-api 对外暴露的模型名；渠道上游模型保持为 ZeroFA 的同名模型。
示例：
your-seedance-model-idpromptstring必填视频生成提示词。new-api 会把它转换成火山 content 中的 text 项。
示例：
一只柴犬在雪地中奔跑，电影级运镜，画面真实自然imagestring可选单张参考图 URL 或 data URI；new-api 会转换为一个 image_url 项。
示例：
https://.../reference.pngimagesstring[]可选多张参考图 URL/data URI 数组；普通多参考图场景推荐使用。
示例：
["https://.../a.png","https://.../b.png"]secondsstring必填视频时长。按当前 DoubaoVideo 转换逻辑使用字符串，例如 "5"。
示例：
5metadata.resolutionstring可选输出分辨率，例如 720p。DoubaoVideo 从 metadata 读取火山结构化参数。
示例：
720pmetadata.ratiostring可选画面比例，例如 16:9。
示例：
16:9metadata.generate_audioboolean可选是否生成音频；Seedance 2.0 支持时可开启。
示例：
true按当前 new-api 代码，seconds 使用字符串；resolution、ratio、generate_audio 等火山参数放入 metadata，避免被通用 /v1/videos 请求结构丢弃。
new-api 的单图、多图与 role
普通图生视频使用顶层 image；多参考图使用顶层 images。new-api 会按数组顺序生成火山 image_url 项，提示词可用“图片1”“图片2”描述每张图的用途。
多参考图 · 推荐格式
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "人物参考图片1，服装参考图片2，场景参考图片3，生成连贯的电影镜头",
"seconds": "5",
"images": [
"https://example.com/person.png",
"https://example.com/outfit.png",
"https://example.com/location.png"
],
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}
}'只有在必须明确保留每张素材的 role 时，才把火山 content 数组放进 metadata.content。new-api 会保留这些图片项，并把顶层 prompt 追加为文本项。
多参考图 · 保留 reference_image role
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "严格参考三张图片中的人物、服装与场景，生成连贯镜头",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"content": [
{
"type": "image_url",
"image_url": {"url": "https://example.com/person.png"},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/outfit.png"},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/location.png"},
"role": "reference_image"
}
]
}
}'不要把 content 直接放在 /v1/videos 顶层：它不属于 new-api 的通用视频请求结构，可能被忽略。metadata.content 是 DoubaoVideo 渠道的厂商扩展，不保证可移植到其他 new-api 视频渠道。
② 通过 new-api 查询任务
使用提交响应里的 id 继续查询同一个 new-api。状态为 queued、in_progress、completed 或 failed。
查询视频任务
TASK_ID="task_xxx"
curl -sS "${NEW_API_BASE}/v1/videos/${TASK_ID}" \
-H "Authorization: Bearer ${NEW_API_KEY}"
# 处理中: {"id":"task_xxx","status":"in_progress","progress":50,...}
# 已完成: {"id":"task_xxx","status":"completed","progress":100,
# "metadata":{"url":"https://..."},...}查询使用 new-api 返回的 task_* 公共任务 ID，不要使用 ZeroFA 或火山内部的 cgt-* ID。完成后视频地址位于 metadata.url。
请求与响应体
用下面的示例确认请求格式与返回结构。需要在线发起请求时，点击页面顶部“调试”拉起在线运行面板。
① 通过 new-api 提交生成
NEW_API_BASE="https://your-new-api.example.com"
NEW_API_KEY="sk-new-api-xxx"
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "一只柴犬在雪地中奔跑，电影级运镜，画面真实自然",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}
}'
# {"id":"task_xxx","task_id":"task_xxx","object":"video",
# "model":"your-seedance-model-id","status":"queued","progress":0}② 通过 new-api 查询任务
TASK_ID="task_xxx"
curl -sS "${NEW_API_BASE}/v1/videos/${TASK_ID}" \
-H "Authorization: Bearer ${NEW_API_KEY}"
# 处理中: {"id":"task_xxx","status":"in_progress","progress":50,...}
# 已完成: {"id":"task_xxx","status":"completed","progress":100,
# "metadata":{"url":"https://..."},...}