VIDEO API

视频生成

使用 RootFlowAI OpenAI-compatible 视频接口提交异步任务、查询状态并下载生成结果。

RootFlowAI 的视频生成接口兼容 OpenAI Videos API。视频任务是异步执行的：先提交任务拿到 task_id，再轮询查询状态，任务完成后通过 content 接口在线播放或下载 MP4。

已完成的视频会保留 7 天，请及时下载保存。视频内容通过 RootFlowAI 代理返回，不暴露上游供应商的原始文件地址。

接口流程

POST /v1/videos
  -> 返回 task_id

GET /v1/videos/{task_id}
  -> 查询 queued / in_progress / completed / failed

GET /v1/videos/{task_id}/content
  -> completed 后下载视频文件

你也可以登录 RootFlowAI 门户，在 /account/video-tasks 查看当前账号的视频任务、预览结果并下载文件。

可用模型

当前开放的视频模型均按次计费，并采用固定的 8 秒、720p 规格。提交时即使传入不同的 seconds 或 resolution，系统也会按公开模型的固定规格处理。

seconds 请写成 JSON 字符串，即 "seconds": "8"。

模型 ID	计费方式	规格说明
`veo-3.1-fast`	按次	Veo 3.1 Fast，固定 8 秒，720p
`veo-3.1`	按次	Veo 3.1，固定 8 秒，720p

实际扣费还会受到你的账号分组倍率影响，请以控制台展示和账单记录为准。

请只使用本页列出的公开模型 ID，其他模型名不会被接受。

提交视频任务

常用请求字段

字段	是否必填	说明
`model`	是	公开模型 ID，例如 `veo-3.1-fast`
`prompt`	是	描述视频内容、主体动作和需要保持的特征
`seconds`	是	当前固定为字符串 `"8"`
`resolution`	是	当前固定为 `"720p"`
`image`	否	PNG 或 JPEG 参考图的 Base64 data URI
`aspect_ratio`	否	推荐使用；支持 `16:9` 和 `9:16`，默认 `16:9`
`orientation`	否	方向别名；支持 `horizontal` 和 `vertical`
`size`	否	通常不要传；如需传入，必须与 `aspect_ratio` 保持一致

文生视频

curl https://api.rootflowai.com/v1/videos \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast",
    "prompt": "一只黑色中华田园犬在阳光明媚的草地上快乐奔跑，真实纪录片风格。",
    "seconds": "8",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

使用参考图生成视频

通过 image 字段传入一张 PNG 或 JPEG 参考图。图片需要使用 data URI，也就是 data:image/...;base64,... 的形式；当前不接受 http:// 或 https:// 图片地址。

下面的示例会读取本地 reference.jpg，转成 Base64 后提交一个竖屏视频任务。示例依赖 jq：

export ROOTFLOWAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
REFERENCE_IMAGE_BASE64="$(base64 < reference.jpg | tr -d '\n')"

jq -n \
  --arg image "data:image/jpeg;base64,${REFERENCE_IMAGE_BASE64}" \
  '{
    model: "veo-3.1",
    prompt: "让参考图中的主体自然运动，保持主体外观和主要特征一致。",
    seconds: "8",
    resolution: "720p",
    aspect_ratio: "9:16",
    image: $image
  }' |
curl https://api.rootflowai.com/v1/videos \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @-

参考图要求：

格式为 PNG 或 JPEG。
单张图片最大 20 MB。
一次任务传一张参考图。
data URI 中的 MIME 类型要与图片格式一致：PNG 使用 data:image/png;base64,，JPEG 使用 data:image/jpeg;base64,。
prompt 中应明确描述希望图片主体如何运动，以及需要保持不变的外观特征。

当前只有 veo-3.1 支持上述参考图传法。veo-3.1-fast 仅支持文生视频，带参考图的请求会在创建上游任务前被拒绝，不会产生上游费用。

控制横屏和竖屏

推荐使用 aspect_ratio 明确指定输出比例：

输出方向	`aspect_ratio`	720p 实际尺寸
横屏	`16:9`	1280 × 720
竖屏	`9:16`	720 × 1280

固定 720p 模型推荐只传 resolution 和 aspect_ratio，不要额外传 size。如果业务代码必须传 size，横屏使用 1280x720，竖屏使用 720x1280；size 与 aspect_ratio 冲突时，上游可能优先采用 size，导致输出方向不符合预期。

横屏请求：

{
  "model": "veo-3.1",
  "prompt": "镜头缓慢向右移动，保持主体清晰。",
  "seconds": "8",
  "resolution": "720p",
  "aspect_ratio": "16:9"
}

竖屏请求：

{
  "model": "veo-3.1-fast",
  "prompt": "主体面向镜头自然运动，适合手机竖屏观看。",
  "seconds": "8",
  "resolution": "720p",
  "aspect_ratio": "9:16"
}

也可以使用方向别名：

{
  "orientation": "horizontal"
}

{
  "orientation": "vertical"
}

horizontal 等同于 16:9，vertical 等同于 9:16。如果同时传入 aspect_ratio 和 orientation，以 aspect_ratio 为准。未传这两个字段时默认生成 16:9 横屏视频。

响应示例：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1782892800
}

记录返回的 id，后续查询和下载都使用这个任务 ID。

查询任务状态

curl https://api.rootflowai.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

状态说明：

状态	含义
`queued`	任务已提交，等待调度
`in_progress`	正在生成
`completed`	生成完成，可以下载
`failed`	生成失败

完成响应示例：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast",
  "status": "completed",
  "progress": 100,
  "created_at": 1782892800,
  "completed_at": 1782893010
}

如果状态是 failed，响应里会带错误信息。失败任务不会返回可下载视频。

如果任务已经生成完成，但系统仍在准备视频存储，可能会短暂看到 video storage is preparing。稍后重新查询任务或下载 content 即可。

下载视频

任务状态为 completed 后，使用 content 接口下载：

curl -L https://api.rootflowai.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxx/content \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -o output.mp4

content 接口返回的是视频二进制内容，通常为 video/mp4。任务未完成时，该接口不会返回视频文件。

下载接口会通过 RootFlowAI 的视频代理读取已转存的视频文件，不会把上游供应商的原始视频 URL 返回给用户。

在门户查看任务

/account/video-tasks

视频任务中心可以查看：

任务 ID
模型
状态和进度
创建时间和更新时间
失败原因
成功任务的视频预览和下载按钮

门户只展示用户自己的视频任务信息。供应商、上游任务 ID、内部路由、采购成本和三方原始视频 URL 不会在用户侧展示。

注意事项

视频生成耗时通常比文本和图片更长，请使用轮询方式查询结果。
当前支持 16:9 横屏和 9:16 竖屏，不支持 1:1 方形视频。
不要在任务未完成时反复下载 content，先查询状态更稳。
已完成的视频会保留 7 天，建议生成完成后及时下载保存视频文件。
如果任务失败，可以根据错误信息调整 prompt、模型或输入素材后重新提交。
API Key 只应保存在服务端或可信环境，不要写进公开前端代码。