Veo-3.1

模型名称：veo-3.1

面向品牌感镜头、电影化叙事和高完成度宣传视频
提交成功后返回视频任务 ID
default / standard 两个分组均可用，参数完全一致
支持纯文生、full_reference 多参考图和 frame_pair 首尾帧
duration 支持 4、6、8 秒
aspect_ratio 支持 16:9、9:16
resolution 支持 720p、1080p、4k

请求鉴权

所有接口均需要使用 Bearer Token 进行认证。

Authorization: Bearer YOUR_API_KEY

提交任务接口

POST /v1/videos

请求参数

字段	类型	必填	默认值	说明
`model`	`string`	是	-	固定传 `veo-3.1`
`prompt`	`string`	是	-	视频生成提示词
`n`	`number`	否	`1`	当前仅支持传 `1`
`images`	`string[]`	否	-	参考图地址数组；`full_reference` 支持 `0-3` 张，`frame_pair` 支持 `1-2` 张
`duration`	`number`	否	`4`	支持 `4`、`6`、`8`
`aspect_ratio`	`string`	否	`16:9`	支持 `16:9`、`9:16`
`resolution`	`string`	否	`720p`	支持 `720p`、`1080p`、`4k`
`reference_mode`	`string`	否	`full_reference`	参考模式，支持 `full_reference` 或 `frame_pair`

不支持 video_urls、audio_urls、草稿、任务链和回调字段。

当前分组说明

当前 veo-3.1 同时支持 default / standard，两个分组共用同一套正式公开能力：

分组	`images` 约束	`duration`	`aspect_ratio`	`resolution`	`reference_mode`
`default / standard`	`full_reference=0-3`；`frame_pair=1-2`	`4 / 6 / 8`	`16:9 / 9:16`	`720p / 1080p / 4k`	`full_reference / frame_pair`

响应

提交成功响应示例：

{
  "id": "video_task_01KQEXAMPLE_VEO31",
  "object": "video",
  "model": "veo-3.1",
  "status": "queued",
  "progress": 0,
  "created_at": 1711111111
}

提交失败响应示例：

{
  "error": {
    "code": 400,
    "type": "invalid_request_error",
    "message": "参数错误，请检查 prompt、images、duration、aspect_ratio、resolution 或 reference_mode 是否符合当前模型要求"
  }
}

任务查询接口

GET /v1/videos/{task_id}

查询成功示例：

{
  "id": "video_task_01KQEXAMPLE_VEO31",
  "object": "video",
  "model": "veo-3.1",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "duration": 6,
    "width": 1920,
    "height": 1080
  },
  "result_url": "https://example.com/result/veo31-video.mp4"
}

使用示例

文生视频

curl --request POST \
  --url https://api.aimaxa.cn/v1/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo-3.1",
    "prompt": "生成一段雨夜街景镜头，霓虹反射在路面，镜头缓慢向前推进",
    "duration": 8,
    "aspect_ratio": "9:16",
    "resolution": "1080p",
    "reference_mode": "full_reference"
  }'

说明：

当前文生视频直接走 default 分组。
文生时可以不传 images。
建议显式传 aspect_ratio 与 resolution，避免按默认值执行。

多参考图视频

curl --request POST \
  --url https://api.aimaxa.cn/v1/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo-3.1",
    "prompt": "保留参考图中的主体和整体光影氛围，生成一段镜头缓慢推进的短视频",
    "n": 1,
    "images": [
      "https://example.com/reference-1.jpg",
      "https://example.com/reference-2.jpg"
    ],
    "duration": 6,
    "reference_mode": "full_reference"
  }'

说明：

full_reference 当前支持 0-3 张参考图。
单参考图、多参考图都走同一条 default 链路。
如已有 OpenAI Images 风格调用，可继续传顶层 size，服务端会兼容转成 aspect_ratio。

首尾帧参考视频

curl --request POST \
  --url https://api.aimaxa.cn/v1/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo-3.1",
    "prompt": "让首帧中的角色向前走近，并自然过渡到尾帧的光线氛围",
    "n": 1,
    "images": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "duration": 6,
    "reference_mode": "frame_pair"
  }'

注意事项

reference_mode=full_reference 时，images 可不传，也可传 1-3 张参考图。
reference_mode=frame_pair 时，首帧必传，尾帧可选，总数为 1-2 张。
4k 生成耗时通常会明显高于 720p 与 1080p。
顶层 size 与 aspect_ratio 兼容，二选一即可。
提交成功后请使用 GET /v1/videos/{task_id} 继续轮询结果。

异步状态与失败响应

视频任务状态只使用 queued、in_progress、completed、failed。处于 queued 或 in_progress 时继续调用查询接口；只有 completed 状态才读取顶层 result_url。任务失败时保持视频对象结构，并返回顶层 error 与 fail_reason，不要按图片接口读取 code/data/works：

{
  "id": "video_task_01KQEXAMPLE_FAILED",
  "object": "video",
  "model": "veo-3.1",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "task_failed",
    "message": "请求处理失败，请稍后重试"
  },
  "fail_reason": "请求处理失败，请稍后重试"
}

开始使用

图像模型

视频模型

文本模型

请求鉴权

提交任务接口

请求参数

当前分组说明

响应

任务查询接口

使用示例

文生视频

多参考图视频

首尾帧参考视频

注意事项

异步状态与失败响应

​请求鉴权

​提交任务接口

​请求参数

​当前分组说明

​响应

​任务查询接口

​使用示例

​文生视频

​多参考图视频

​首尾帧参考视频

​注意事项

​异步状态与失败响应

请求鉴权

提交任务接口

请求参数

当前分组说明

响应

任务查询接口

使用示例

文生视频

多参考图视频

首尾帧参考视频

注意事项

异步状态与失败响应