跳转到内容
伯跃科技 · 文档

兼容接口

火山国内线已上线

这一页写给已经在用 OpenAI 视频格式（/v1/videos）的接入方：哪些参数会生效，哪些会被悄悄丢掉，以及怎么写才不丢参数。

先看这个

Section titled “先看这个”

POST /v1/videos 字段对照

Section titled “POST /v1/videos 字段对照”
位置 字段 是否生效
顶层 model、prompt、seconds（或 duration）、images（图片地址数组） 生效
顶层 size、resolution、ratio、generate_audio 丢弃。size 虽然不会下发给模型，但仍会参与预扣估算，所以预扣金额可能和实际出片规格对不上
顶层 input_reference、image 丢弃。参考图丢了，任务就退化成纯文生视频
metadata 方舟协议的其他字段，如 resolution、ratio、generate_audio、watermark、return_last_frame 生效（实测不丢）
metadata.content 里面的 text 提示词 丢弃。提示词必须写在顶层的 prompt
multipart 文件 上传文件 参考素材请用链接传入（写在 metadata.content）

时长用顶层 seconds，写字符串（如 "5"，与 OpenAI 格式一致）或数字都可以；duration 也会被当成 seconds。

全保真写法

Section titled “全保真写法”

下面是推荐的写法：提示词放顶层 prompt，时长用 seconds，其余方舟参数全部放进 metadata。

终端窗口
curl -sS https://api.boyueasi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "一只橘猫在窗台上伸懒腰，阳光透过窗帘",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true
    }
  }'

对比下面这种常见的错误写法，resolution 和 ratio 写在了顶层，会被丢弃，模型拿不到这两个参数：

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "一只橘猫在窗台上伸懒腰，阳光透过窗帘",
  "seconds": "5",
  "resolution": "720p",
  "ratio": "16:9"
}

GET /v1/videos/{id}

Section titled “GET /v1/videos/{id}”

查询接口只返回任务状态和进度，不含视频链接，也不含用量。返回的主要字段是 id、object（固定为 video）、model、status、progress、created_at 和 completed_at；任务失败时另带 error 对象（message、code）。status 的取值是 queued、in_progress、completed、failed。

要拿到视频，请求 GET /v1/videos/{id}/content，{id} 填任务号，带 Authorization: Bearer <API 密钥>，返回 video/mp4，支持 Range。它不支持 HEAD 请求，而且要经网关转发，速度比较慢，细节见查询任务与获取视频里的「视频链接」。

如果你需要视频直链、尾帧图或者 usage 用量，请改用原生接口的查询任务。

POST /v1/video/generations

Section titled “POST /v1/video/generations”

这是旧的统一格式，规则和上面基本一致，只有时长有一个坑：

  • 顶层的 duration（整数）不会生效。时长要写成 seconds（字符串），或者放进 metadata.duration。
  • 顶层的 size 只影响预扣估算，不会下发给模型。
  • 参考图片地址写进 images 数组。
  • 其余方舟参数一律放进 metadata，实测不会丢。
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "一只橘猫在窗台上伸懒腰，阳光透过窗帘",
  "seconds": "5",
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9"
  }
}

返回里可能有文档没有列出的字段，不用处理，忽略即可。

对账实证

Section titled “对账实证”

参数写错位置，出片规格就会和你想要的不一样：顶层的 resolution、ratio、generate_audio 会被丢弃，实际出片取模型的默认值；而预扣是按你写的 size 与 seconds 估算的（没写 size 时按 1080p 档估算），两者可能对不上。最终仍按实际出片用量结算，多退少补。所以别图省事，方舟参数一律放进 metadata，时长用顶层 seconds。

© 伯跃科技