何时使用
标准 /v1/videos 和 /v1/images/generations 已覆盖通用调用。当需要火山新发布的高级参数、Seedance 专属控制项或 Seedream 原生字段时，可以通过 /ark 直接发送原始 body。
目前 /ark 仅开放图片生成，以及视频任务的提交和查询端点；其他火山能力继续使用标准接口。
路径映射：/ark 对应火山 /api
火山方舟原生地址在域名后使用 /api。通过 ZeroFA 调用时，把这一段 /api 替换为 /ark，其后的 /v3/contents/... 保持不变。直接调用推荐使用 /ark/v3/...。
同一端点的三种地址
火山原生 https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
ZeroFA 推荐 https://zerofa.ai/ark/v3/contents/generations/tasks
new-api 兼容 https://zerofa.ai/ark/api/v3/contents/generations/tasks两种 ZeroFA 路径最终都会转发到火山 /api/v3/contents/generations/tasks；请求体、查询参数和响应均保持火山原生格式。
通过 new-api 接入
在 new-api 新建或编辑用于火山视频的渠道，将自定义 API 地址（Base URL）设为 ZeroFA 的 /ark 根地址，填写 ZeroFA API Key，并配置要使用的 Seedance 模型。new-api 会自动追加火山的 /api/v3/... 路径。
new-api 渠道配置
# new-api 渠道中的上游配置
API 地址 / Base URL: https://zerofa.ai/ark
API Key: sk-zerofa-xxx
模型: your-seedance-model-id
# new-api 自动发出的任务请求（无需手工拼接）
POST https://zerofa.ai/ark/api/v3/contents/generations/tasks
GET https://zerofa.ai/ark/api/v3/contents/generations/tasks/{task_id}Base URL 只填写到 /ark，不要填写 /ark/api/v3。ZeroFA 已兼容 new-api 生成的 /ark/api/v3/...，并会归一化后转发给火山。
火山原生两步流程
① 提交
POST /ark/v3/contents/generations/tasks火山原生 body必填Body 为火山方舟创建视频任务的原始请求体，包括 model 和 content 数组。返回原始响应，其中 id 为火山 task id。提交不扣费。
② 轮询
GET /ark/v3/contents/generations/tasks/:idid = 火山 task id必填查询会原样转发并返回火山原始响应。status=succeeded 时包含 content.video_url，并在首次成功时按时长幂等扣费。
此 id 是 cgt-* 格式的火山原生 task id，可通过推荐的 /ark/v3/.../:id 或 new-api 兼容的 /ark/api/v3/.../:id 查询；它与标准 /v1/videos 使用的平台 task id 不互通。
请求字段以火山官方文档为准
/ark 是原生透传入口，不重新定义火山的 content、role、模型参数或素材限制。本站仅说明路径、鉴权和任务查询方式；请求体及各模型能力请直接查阅火山最新官方文档。
调用时只需把火山地址中的 /api 替换为本站 /ark，并使用本站 API Key；不要根据本站示例推断厂商全部字段。火山新增或调整字段时，以官方文档为唯一准则。
计费模型
视频成功后按时长和模型单价幂等结算；图片成功后按实际张数结算。失败均释放预留，不交付未结算结果。
请求与响应体
用下面的示例确认请求格式与返回结构。需要在线发起请求时，点击页面顶部“调试”拉起在线运行面板。
① 提交（火山原始 body）
# 火山原始 body：content 数组和高级 flag 均原样透传
# 路径规则：用 /ark 替换火山域名后的 /api
curl https://zerofa.ai/ark/v3/contents/generations/tasks \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"content": [
{ "type": "text",
"text": "一只柴犬在雪地奔跑 --ratio 16:9 --duration 5 --resolution 720p" },
{ "type": "image_url",
"image_url": { "url": "https://.../dog.png" },
"role": "first_frame" }
]
}'
# 火山原始响应:{"id":"cgt-..."}② 轮询（火山原始响应）
curl https://zerofa.ai/ark/v3/contents/generations/tasks/cgt-xxx \
-H "Authorization: Bearer sk-zerofa-xxx"
# 火山原始响应（原样透传）
# {"id":"cgt-...","status":"succeeded",
# "content":{"video_url":"https://...volces.com/....mp4"},
# "usage":{"completion_tokens":108900,...},
# "seed":83017,"resolution":"720p","ratio":"16:9", ...}