何时使用
标准 /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/tasksZeroFA 会将推荐路径转发到火山 /api/v3/contents/generations/tasks；请求体、查询参数和响应均保持火山原生格式。
通过 new-api 接入
在 new-api 新建或编辑用于火山视频的渠道，将自定义 API 地址（Base URL）设为 ZeroFA 的 /ark 根地址，填写 ZeroFA API Key，并配置要使用的 Seedance 模型。其余路由由 new-api 与 ZeroFA 自动处理。
new-api 渠道配置
# new-api 渠道中的上游配置
API 地址 / Base URL: https://zerofa.ai/ark
API Key: sk-zerofa-xxx
模型: your-seedance-model-idBase URL 只填写到 /ark 根地址，无需手工拼接任务路径。
火山原生两步流程
① 提交
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，并在首次成功时按时长幂等扣费。
③ 任务列表（分页）
GET /ark/v3/contents/generations/taskspage_num / page_size / filter.*可选按火山列表契约分页返回当前账号的视频任务。id 为本站任务号（与轮询端点互通）；列表为纯读库快照，非终态任务以 queued/running 呈现，不会逐条查询上游。item 字段与查询端点同形：model 为本站模型名，resolution/duration/usage 为请求（交付）档口径，请求了尾帧的任务在 content.last_frame_url 返回尾帧图。
page_numinteger可选页码，从 1 开始，默认 1
page_sizeinteger可选每页条数，1–100，默认 10
filter.statusstring可选按状态过滤，可逗号分隔多值：queued / running / succeeded / failed / cancelled
filter.task_idsstring可选按任务号过滤，可逗号分隔多个本站任务号
filter.modelstring可选按模型名过滤
filter.service_tierstring可选接受该参数但当前不影响过滤（本站按模型原价路由）
此 id 是 cgt-* 格式的火山原生 task id，可通过 /ark/v3/.../:id 查询；它与标准 /v1/videos 使用的平台 task id 不互通。
提交带 return_last_frame:true 时，查询/列表响应的 content.last_frame_url 返回尾帧图。链接为短期签名（约 24 小时），过期后重新查询任务即可获取新链接；请及时下载留存。
样片（Draft）模式
Seedance 2.5 支持两步式生成：先生成 480p 预览样片验证效果，再基于样片 ID 生成 1080p 成片。两步各自独立计费：样片按 480p 计费，成片按目标分辨率（1080p）计费，token 单价根据样片是否含输入视频确定。样片任务 ID 有效期为 7 天。
① Step1：生成 480p 样片
# 样片模式 Step1：生成 480p 预览样片
# 顶层 draft:true + resolution 480p（仅支持 480p）
curl -X POST "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" }
],
"draft": true,
"resolution": "480p"
}'
# → {"id":"cgt-..."} 记住这个 task id，Step2 需要用它② Step2：基于样片 ID 生成 1080p 成片
# 样片模式 Step2：基于样片 ID 生成 1080p 成片
# content 只带 draft_task 引用，resolution 固定 1080p（仅支持 1080p）
curl -X POST "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": "draft_task", "draft_task": { "id": "cgt-..." } }
],
"resolution": "1080p"
}'
# → 成片 resolution=1080p，其余参数（提示词/参考素材/时长/比例/seed/音频）由 Step1 自动复用样片模式参数
draftboolean可选顶层 draft:true 开启样片模式。仅支持 480p 分辨率，设置其他分辨率会报错。
draft_task.idstring可选Step2 中 content 数组携带 draft_task 引用，id 为 Step1 返回的任务号（用本站任务号即可，平台会自动还原为火山 task id）。
resolutionstring可选Step1 固定 480p，Step2 固定 1080p，设置其他分辨率会报错。
Step2 的 content 只带 draft_task 引用，提示词、参考素材、时长、比例、seed、音频等参数由模型自动复用 Step1，请勿重复传入（传了会被上游拒绝）。成片在结构、构图、动作与样片高度一致。
请求字段以火山官方文档为准
/ark 是原生透传入口，不重新定义火山的 content、role、模型参数或素材限制。若模型配置了默认码率且请求未传 bitrate_mode，本站会补入该默认值；其他字段保持原生语义。请求体及各模型能力请直接查阅火山最新官方文档。
调用时只需把火山地址中的 /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-...","model":"your-seedance-model-id","status":"succeeded",
# "content":{"video_url":"https://...","last_frame_url":"https://..."},
# "usage":{"completion_tokens":108900,"total_tokens":108900},
# "created_at":1779354227,"updated_at":1779354426,
# "seed":83017,"resolution":"720p","ratio":"16:9","duration":5,
# "framespersecond":24,"service_tier":"default","execution_expires_after":172800,
# "generate_audio":true,"draft":false,"priority":0,"output_format":"mp4"}③ 任务列表（分页）
curl "https://zerofa.ai/ark/v3/contents/generations/tasks?page_num=1&page_size=10&filter.status=succeeded" \
-H "Authorization: Bearer sk-zerofa-xxx"
# {"total":30,"items":[
# {"id":"cgt-...","model":"your-seedance-model-id","status":"succeeded",
# "content":{"video_url":"https://...","last_frame_url":"https://..."},
# "usage":{"completion_tokens":108900,"total_tokens":108900},
# "created_at":1779354227,"updated_at":1779354426,
# "seed":39832,"resolution":"720p","ratio":"16:9","duration":5,
# "framespersecond":24,"service_tier":"default","execution_expires_after":172800,
# "generate_audio":true,"draft":false,"priority":0,"output_format":"mp4"}]}