Veo 3.1

Veo 3.1 使用统一异步任务接口：提交任务后保存返回的 id，再通过查询接口获取状态和视频 URL。当前提供标准版与 Fast 版两个模型。

选择模型

模型	文生视频	普通参考图	首尾帧	定位
`veo-3.1-generate-preview`	支持	最多 3 张	支持，必须成对提供	质量优先
`veo-3.1-fast-generate-preview`	支持	不支持	支持，必须成对提供	速度优先

快速了解

项目	支持范围
任务流程	`POST /v1/task/submit` 提交，`GET /v1/task/{task_id}` 查询
视频时长	4 秒、6 秒、8 秒
清晰度	720p、1080p
画面比例	`16:9`、`9:16`
生成数量	`n` 固定为 `1`
音频生成	默认开启；传 `audio: false` 可关闭

请求使用 Bearer 认证，生成参数统一放在 input 对象中：

Authorization: Bearer $API_KEY

input 参数

字段	类型	必填	说明
`prompt`	string	是	视频提示词
`duration`	integer	是	`4`、`6`、`8`
`aspect_ratio`	string	是	`16:9`、`9:16`
`resolution`	string	是	`720p`、`1080p`
`image_references`	array	否	普通参考图，最多 3 张；仅标准版支持
`start_frames`	array	否	首帧，只能传 1 张；必须同时提供尾帧
`end_frames`	array	否	尾帧，只能传 1 张；必须同时提供首帧
`seed`	integer	否	`-1` 表示随机，也可以传非负整数
`audio`	boolean	否	是否生成音频，默认 `true`
`n`	integer	否	当前固定为 `1`

两个模型都不支持 video_references 或 audio_references。参考图片支持公网 URL、data URI、纯 base64 或 {"url": "..."} 对象。

素材组合规则

模式	标准版	Fast 版	规则
文生视频	支持	支持	不传任何参考素材
普通参考图	支持	不支持	标准版最多传 3 张 `image_references`
首尾帧	支持	支持	`start_frames` 和 `end_frames` 各传 1 张
只传首帧或尾帧	不支持	不支持	两个字段必须同时提供
普通参考图 + 首尾帧	不支持	不支持	两种模式不能混用

不完整的首尾帧请求会在本地校验阶段被拒绝，不会上传素材或创建上游任务。

请求示例

curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "input": {
      "prompt": "根据三张参考图生成连贯的电影广告镜头",
      "duration": 8,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "image_references": [
        "https://example.com/subject.png",
        "https://example.com/scene.png",
        "https://example.com/style.png"
      ],
      "seed": 66047,
      "audio": true,
      "n": 1
    }
  }'

curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "input": {
      "prompt": "从首帧自然过渡到尾帧，保持主体一致",
      "duration": 4,
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "start_frames": [
        "https://example.com/first.png"
      ],
      "end_frames": [
        "https://example.com/last.png"
      ],
      "seed": -1,
      "audio": true,
      "n": 1
    }
  }'

curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "input": {
      "prompt": "雨后的未来城市，镜头沿街道平稳前进",
      "duration": 6,
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "seed": -1,
      "audio": true,
      "n": 1
    }
  }'

获取结果

提交成功后会返回任务 ID：

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "queued",
  "phase": "queued",
  "created_at": 1784697600,
  "progress": null
}

使用 id 查询任务：

curl https://cdn.12ai.org/v1/task/task_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $API_KEY"

在 queued 或 processing 状态下每 3–5 秒查询一次。完成后从 outputs[0] 读取视频 URL：

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "completed",
  "phase": "completed",
  "progress": 100,
  "outputs": [
    "https://img.12ai.org/videos/task_xxxxxxxxxxxxxxxx_0.mp4"
  ],
  "error": null
}

失败时查看 error.code 和 error.message，并停止轮询。