火山引擎 · 原生透传(/ark)

直接用火山方舟原始请求体 + 全部高级参数,LOLAI 注入 key 原样转发、不做字段适配。请求/响应都是火山原生格式;计费同 /v1/videos(成功按时长扣)。

生产环境POSThttps://api.lolai.lol/ark/v3/contents/generations/tasks

什么时候用它

标准 /v1/videos 已覆盖文生 / 图生 / 首尾帧 / 多模态参考。当你需要它没暴露的火山高级参数(新出的 --flag、Seedance 特有控制项等)时,用 /ark 直接发火山原始 body,所有参数透传,不被我们的字段约束。

目前 /ark 只开放视频 task 两个端点。图片等其它火山能力仍走标准端点。

两步式(火山原生)

① 提交

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;此时首次按时长幂等扣费(同 /v1/videos)。

这里的 id 是火山原生 task id(cgt-…),只能用 /ark/v3/.../:id 查; 它与标准 /v1/videos 的 task id 不互通(那条用我们自己的 id),两套各查各的。

content 数组(火山原生格式)

火山 content item 形如 {type, <type>:{url}, role},role 在 item 顶层:

text —— prompt + --ratio / --duration / --resolution 等 flag
image_url + role first_frame / last_frame / reference_image
video_url + role reference_video;audio_url + role reference_audio

计费

计费时长从 body 的 --duration N flag 读取(抽不到兜底 5 秒),成功后按 时长 × 模型单价幂等扣费,失败不扣。务必在 --duration 写清,否则按 5 秒计。

请求与响应体

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

① 提交(火山原始 body)

# 火山原始 body:content 数组 + --flag 高级参数,全部直达火山
# 路径镜像火山原生 /api/v3/contents/...(host 后插 ark 命名空间)
curl https://api.lolai.lol/ark/v3/contents/generations/tasks \
  -H "Authorization: Bearer sk-lolai-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "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://api.lolai.lol/ark/v3/contents/generations/tasks/cgt-xxx \
  -H "Authorization: Bearer sk-lolai-xxx"

# 火山原始响应(原样透传):
# {"id":"cgt-...","status":"succeeded",
#  "content":{"video_url":"https://...volces.com/....mp4"},
#  "usage":{"completion_tokens":108900,...},
#  "seed":83017,"resolution":"720p","ratio":"16:9", ...}