文档 / 视频系列 / Veo

VeoPOSTveo-3.1veo-3.1-fastveo-3.1-lite

Veo 3.1 视频生成

Veo 3.1 系列视频生成(veo-3.1 / veo-3.1-fast / veo-3.1-lite,支持文生视频与图生视频):请求字段、JSON 与表单传参考图示例、提交异步任务、轮询状态、下载 MP4。

POSThttps://api.apimax.ai/v1/videos

Bearer API KeyJSON服务端调用

概述#

Veo 3.1 系列视频生成模型,分标准(veo-3.1)/ 高速(veo-3.1-fast)/ 轻量(veo-3.1-lite)三档。三档共享同一套接口、请求字段与状态机,仅模型名与计费单价不同;Lite 档的参考图能力有单独限制(至多 2 张,按首尾帧口径,见下文)。全系支持文生视频与图生视频(参考图、首尾帧),通过统一视频接口提交异步生成任务:提交成功后立即返回平台任务 ID,轮询到 completed 后,使用响应中的 url 下载 MP4。

本系列模型名为 veo-3.1、veo-3.1-fast、veo-3.1-lite,必须与请求体完全一致。示例统一用 veo-3.1,换成其他两档模型名即可。

接口#

http

POST /v1/videos

请求需要携带 API Key:

http

Authorization: Bearer <token>
Content-Type: application/json

POST /v1/videos/generations 与 POST /v1/video/generations 为等价别名路径。

也可用通用任务接口 GET /v1/tasks/{task_id} 查询任务(见查询任务状态);POST /v1/responses 同样支持该系列模型(Responses 兼容格式,支持流式与后台任务)。

请求字段#

字段	类型	必填	说明
`model`	`string`	是	`veo-3.1` / `veo-3.1-fast` / `veo-3.1-lite`(标准 / 高速 / 轻量三档,接口与字段完全一致,仅单价不同)
`prompt`	`string`	是	视频内容、运动、镜头与风格描述
`seconds`	`integer / string`	否	视频时长,枚举 4 / 6 / 8 秒,默认 8 `duration` 为兼容别名,`seconds` 优先
`resolution`	`string`	否	`720p` 或 `1080p`,默认 720p;要 1080p 须显式传 `resolution` 或 `size`
`size`	`string`	否	目标画布,格式 `WIDTHxHEIGHT`(如 `1280x720`,也认 `720p` / `1080p` 档位字面量) 按短边映射分辨率,优先于 `resolution`
`aspect`	`string`	否	画面比例,`16:9`(默认)/ `9:16` `ratio`、`aspect_ratio` 为兼容别名,优先级 `aspect` > `ratio` > `aspect_ratio`
`image_urls`	`[]string / string`	否	参考图,最多 3 张;数组为主形态,单串也收条目两种形态:字符串——URL(http/https)或 base64(不含 `data:` 前缀);对象——`{"url": "https://…"}`(OpenAI 官方 videos 形态,其余键忽略,缺 `url` 键 400),数组内字符串与对象可混排参考图与首尾帧不要同传(同传时上游会舍弃);Lite 档至多 2 张:第一张按首帧、第二张按尾帧口径提交等价字段 ≡(完全同义、可混用、合并计数,合并序 `reference` → `image_urls` → `images` → `image` → `reference_images` → `input_reference`):`reference`、`images`、`image`、`reference_images`、`input_reference`(后两个为 OpenAI 官方 videos 名);multipart 文件 part 名同套,各配 `[]` 变体
`first_frame`	`string`	否	首帧图(单张,URL 或 base64,三档均支持) 与参考图不要同传:同时传时上游会舍弃
`last_frame`	`string`	否	尾帧图(单张) 必须与 `first_frame` 同传,孤立尾帧会被拒绝
`audio`	`boolean`	否	音轨开关:`true` 时成片同步生成对白 / 音效 / 音乐,缺省 `false` 出无声片;`generate_audio` 为同义别名

尺寸映射#

传入 size 后按短边选择分辨率档位:

`size`	实际分辨率
`1920x1080`、`1080x1920`、`1080x1080`	`1080p`
`1280x720`、`720x1280`	`720p`

短边低于 720 的尺寸会被拒绝。需要精确控制时直接传 resolution。

参考图与首尾帧示例#

参考图(image_urls 与等价字段可混用,合计 ≤3 张):

json

{
  "model": "veo-3.1",
  "prompt": "animate this style",
  "image_urls": ["https://cdn.example.com/style-ref.png"]
}

OpenAI 官方对象形态(reference_images,条目为 {"url": …} 对象,可与字符串形态混排):

json

{
  "model": "veo-3.1",
  "prompt": "a paper boat drifting along a stream",
  "reference_images": [
    { "url": "https://cdn.example.com/char.png" },
    { "url": "https://cdn.example.com/style.png" }
  ]
}

首尾帧(各单张,last_frame 必须与 first_frame 同传):

json

{
  "model": "veo-3.1",
  "prompt": "a paper boat drifting along a stream",
  "first_frame": "https://cdn.example.com/start.png",
  "last_frame": "https://cdn.example.com/end.png"
}

参考图与首尾帧不要同传:同时传时上游会舍弃。按需求二选一——多参考图走 image_urls,首尾定格走 first_frame / last_frame。

需要竖版必须显式传 aspect: "9:16"(或竖图 size,如 720x1280);不带比例一律按 16:9 横版出片。

veo-3-1-lite 的参考图能力与系列其他两档不同:上游至多接受 2 张 图,按 第一张=首帧、第二张=尾帧 口径提交(等效 first_frame + last_frame)。image_urls 及其等价字段合计超过 2 张,或参考图与 first_frame / last_frame 同传,请求会被拒绝(400)。需要 3 张参考图请改用 veo-3.1 或 veo-3.1-fast。

表单(multipart)模式#

Content-Type: multipart/form-data,文本字段与 JSON 入口同义:model / prompt / seconds / duration / resolution / size / aspect / ratio / aspect_ratio / audio(true / 1 / on 收,非法值 400)。图片以二进制文件 part 传入:

参考图文件字段名与 JSON 侧同套:reference、image_urls、images、image、reference_images、input_reference,各可用 [] 数组风格写法(十二种拼法全收合并,合计 ≤3 张;Lite 档合计至多 2 个,第一张按首帧、第二张按尾帧,且不能与首尾帧同传)
首尾帧为单槽字段 first_frame / last_frame,各至多一个 part

首尾帧(标准 / 高速档;不要与参考图同传):

cURL

curl --request POST \
  --url https://api.apimax.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --form model=veo-3.1 \
  --form prompt='a paper boat drifting along a stream' \
  --form seconds=8 \
  --form resolution=1080p \
  --form first_frame=@start.png \
  --form last_frame=@end.png

只传参考图(多个同名 part,标准 / 高速档):

cURL

curl --request POST \
  --url https://api.apimax.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --form model=veo-3.1-fast \
  --form prompt='animate this style' \
  --form reference=@ref1.png \
  --form reference=@ref2.png

multipart 仅支持二进制文件 part:URL 或 base64 形态的参考图/首尾帧(字符串值)一律返回 400,请改走 JSON 入口对应字段。

提交任务#

完整参数示例:

cURL

curl --request POST \
  --url https://api.apimax.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo-3.1",
    "prompt": "雨后的东京街头,一辆复古跑车缓缓驶过霓虹灯牌,电影感镜头",
    "seconds": 8,
    "resolution": "1080p"
  }'

OpenAI 官方格式示例——seconds 用字符串形态、size 用像素形,与 OpenAI 视频接口(Sora 风格)一致,可直接用 OpenAI SDK 或官方示例代码对接:

cURL

curl --request POST \
  --url https://api.apimax.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo-3.1",
    "prompt": "A golden retriever running along the beach at sunset, cinematic lighting",
    "seconds": "8",
    "size": "1280x720"
  }'

带音轨(对白 / 音效 / 音乐同步生成,缺省无声):

cURL

curl --request POST \
  --url https://api.apimax.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo-3.1",
    "prompt": "新闻主播在演播室播报天气,面对镜头自然讲述",
    "audio": true,
    "seconds": 8
  }'

最简请求只传 model 与 prompt,时长/分辨率/比例取默认(8 秒、720p、16:9):

cURL

curl --request POST \
  --url https://api.apimax.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"model": "veo-3.1-lite", "prompt": "一只金毛犬在海边奔跑,夕阳逆光"}'

竖版(9:16)示例:

cURL

curl --request POST \
  --url https://api.apimax.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo-3.1",
    "prompt": "竖屏运镜:无人机自低空拉升至城市天际线",
    "aspect": "9:16",
    "seconds": 6
  }'

提交响应#

200

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

id 为平台任务 ID,用于后续轮询与下载;model 回显实际请求的模型名。

查询任务#

cURL

curl --request GET \
  --url https://api.apimax.ai/v1/videos/task_NtOU1d2Pu9HkppPvEKQbXFR2k5f2UqVe \
  --header 'Authorization: Bearer <token>'

任务状态:queued(排队)→ in_progress(生成中,progress 0 ~ 100)→ completed / failed。建议 5 ~ 10 秒间隔轮询。

完成响应示例:

200

{
  "id": "task_NtOU1d2Pu9HkppPvEKQbXFR2k5f2UqVe",
  "object": "video",
  "model": "veo-3.1",
  "status": "completed",
  "progress": 100,
  "prompt": "雨后的东京街头,一辆复古跑车缓缓驶过霓虹灯牌,电影感镜头",
  "seconds": "8",
  "created_at": 1791606210,
  "completed_at": 1791606305,
  "url": "https://api.apimax.ai/v1/videos/task_NtOU1d2Pu9HkppPvEKQbXFR2k5f2UqVe/content"
}

下载视频#

url 即下载地址,返回 video/mp4,支持 Range 断点请求:

cURL

curl --request GET \
  --url https://api.apimax.ai/v1/videos/task_NtOU1d2Pu9HkppPvEKQbXFR2k5f2UqVe/content \
  --header 'Authorization: Bearer <token>' \
  -o video.mp4

计费#

按分辨率 × 时长计费,三档单价不同:提交时按请求参数(时长、分辨率)预扣,任务完成后按实际时长与分辨率结算。当前各档单价以平台「模型价格」页为准。

字段

类型

必填

说明

model

string

是

veo-3.1 / veo-3.1-fast / veo-3.1-lite(标准 / 高速 / 轻量三档,接口与字段完全一致,仅单价不同)

prompt

string

是

视频内容、运动、镜头与风格描述

seconds

integer / string

否

视频时长,枚举 4 / 6 / 8 秒,默认 8
duration 为兼容别名,seconds 优先

resolution

string

否

720p 或 1080p,默认 720p;要 1080p 须显式传 resolution 或 size

size

string

否

目标画布,格式 WIDTHxHEIGHT(如 1280x720,也认 720p / 1080p 档位字面量)
按短边映射分辨率,优先于 resolution

aspect

string

否

画面比例,16:9(默认)/ 9:16
ratio、aspect_ratio 为兼容别名,优先级 aspect > ratio > aspect_ratio

image_urls

[]string / string

否

参考图,最多 3 张;数组为主形态,单串也收
条目两种形态:字符串——URL(http/https)或 base64(不含 data: 前缀);对象——{"url": "https://…"}(OpenAI 官方 videos 形态,其余键忽略,缺 url 键 400),数组内字符串与对象可混排
参考图与首尾帧不要同传(同传时上游会舍弃);Lite 档至多 2 张:第一张按首帧、第二张按尾帧口径提交
等价字段 ≡(完全同义、可混用、合并计数,合并序 reference → image_urls → images → image → reference_images → input_reference):reference、images、image、reference_images、input_reference(后两个为 OpenAI 官方 videos 名);multipart 文件 part 名同套,各配 [] 变体

first_frame

string

否

首帧图(单张,URL 或 base64,三档均支持)
与参考图不要同传:同时传时上游会舍弃

last_frame

string

否

尾帧图(单张)
必须与 first_frame 同传,孤立尾帧会被拒绝

audio

boolean

否

音轨开关:true 时成片同步生成对白 / 音效 / 音乐,缺省 false 出无声片;generate_audio 为同义别名

size

实际分辨率

1920x1080、1080x1920、1080x1080

1080p

1280x720、720x1280

720p

{ "model": "veo-3.1", "prompt": "a paper boat drifting along a stream", "reference_images": [ { "url": "https://cdn.example.com/char.png" }, { "url": "https://cdn.example.com/style.png" } ] }

curl --request POST \ --url https://api.apimax.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --form model=veo-3.1 \ --form prompt='a paper boat drifting along a stream' \ --form seconds=8 \ --form resolution=1080p \ --form first_frame=@start.png \ --form last_frame=@end.png

curl --request POST \ --url https://api.apimax.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --form model=veo-3.1-fast \ --form prompt='animate this style' \ --form reference=@ref1.png \ --form reference=@ref2.png

curl --request POST \ --url https://api.apimax.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "veo-3.1", "prompt": "雨后的东京街头,一辆复古跑车缓缓驶过霓虹灯牌,电影感镜头", "seconds": 8, "resolution": "1080p" }'

curl --request POST \ --url https://api.apimax.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "veo-3.1", "prompt": "A golden retriever running along the beach at sunset, cinematic lighting", "seconds": "8", "size": "1280x720" }'

curl --request POST \ --url https://api.apimax.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "veo-3.1", "prompt": "新闻主播在演播室播报天气,面对镜头自然讲述", "audio": true, "seconds": 8 }'

curl --request POST \ --url https://api.apimax.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{"model": "veo-3.1-lite", "prompt": "一只金毛犬在海边奔跑,夕阳逆光"}'

curl --request POST \ --url https://api.apimax.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "veo-3.1", "prompt": "竖屏运镜:无人机自低空拉升至城市天际线", "aspect": "9:16", "seconds": 6 }'

{ "id": "task_NtOU1d2Pu9HkppPvEKQbXFR2k5f2UqVe", "object": "video", "model": "veo-3.1", "status": "completed", "progress": 100, "prompt": "雨后的东京街头,一辆复古跑车缓缓驶过霓虹灯牌,电影感镜头", "seconds": "8", "created_at": 1791606210, "completed_at": 1791606305, "url": "https://api.apimax.ai/v1/videos/task_NtOU1d2Pu9HkppPvEKQbXFR2k5f2UqVe/content" }

概述#

接口#

请求字段#

尺寸映射#

参考图与首尾帧示例#

表单(multipart)模式#

提交任务#

提交响应#

查询任务#

下载视频#

计费#

下一步

概述#

接口#

请求字段#

尺寸映射#

参考图与首尾帧示例#

表单(multipart)模式#

提交任务#

提交响应#

查询任务#

下载视频#

计费#

下一步