ZeroFA API

火山引擎 · 原生透传（/ark）

直接使用火山方舟原始请求体和高级参数。ZeroFA 注入 key 后原样转发，不适配字段；请求和响应保持火山原生格式，成功后按视频时长计费。

POSThttps://zerofa.ai/ark/v3/contents/generations/tasks

何时使用

标准 /v1/videos 已覆盖文生视频、图生视频、首尾帧和多模态参考。当需要尚未暴露的火山高级参数或 Seedance 专属控制项时，可以通过 /ark 直接发送原始 body。

目前 /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，并在首次成功时按时长幂等扣费。
此 id 是 cgt-* 格式的火山原生 task id，只能通过 /ark/v3/.../:id 查询；它与标准 /v1/videos 使用的平台 task id 不互通。

content 数组（火山原生格式）

火山 content item 包含 type、对应类型数据和顶层 role。常见组合：

  • text：prompt 及 --ratio、--duration、--resolution 等 flag
  • image_url：role 可为 first_frame、last_frame 或 reference_image
  • video_url 配合 reference_video；audio_url 配合 reference_audio

计费模型

计费时长从 body 中的 --duration N 读取，无法解析时按 5 秒计算。成功后按时长和模型单价幂等扣费，失败不扣费。

请求与响应体

用下面的示例确认请求格式与返回结构。需要在线发起请求时，点击页面顶部“调试”拉起在线运行面板。

① 提交（火山原始 body）
# 火山原始 body：content 数组和高级 flag 均原样透传
# 路径镜像火山原生接口，并在 host 后加入 ark 命名空间
curl https://zerofa.ai/ark/v3/contents/generations/tasks \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0-lol",
    "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", ...}