Veo 3.1 官方版

veo-3.1-official 支持文生视频、首帧和首尾帧生成，可选择 fast 或 quality 模式，生成 4、6 或 8 秒的 720p、1080p 或 4k 视频。音频默认关闭，可通过 generate_audio 开启。

本页介绍独立模型 veo-3.1-official。使用 veo-3 或 veo-3-extend 时，请查阅 Veo 3.1 文档，两者的参数和计费方式不同。

模型与接口

用途	接口
创建视频任务	`POST https://api.aivideoapi.ai/v1/videos/generations`
估算积分	`POST https://api.aivideoapi.ai/v1/estimate`
查询任务	`GET https://api.aivideoapi.ai/v1/tasks/{taskId}`

生成和查询需要在请求头中传入 Authorization: Bearer sk-your-api-key，详见鉴权。创建和估价请求均使用 Content-Type: application/json。

计费

按模式、分辨率、是否生成音频和请求时长计费。下表为账户倍率应用前的每秒积分，输入图片不额外收费。

模式	分辨率	无音频：积分/秒	有音频：积分/秒
`fast`	`720p`	16.64	20.80
`fast`	`1080p`	20.80	24.96
`fast`	`4k`	52.00	62.40
`quality`	`720p`	41.60	83.20
`quality`	`1080p`	41.60	83.20
`quality`	`4k`	83.20	124.80

基础积分 = 每秒积分 × 请求时长。最终积分在基础积分上应用账户倍率，按精确十进制四舍五入至两位小数。

只传入 prompt 时，默认使用 fast、8 秒、720p、16:9、无音频，标准倍率 1 下费用为 16.64 × 8 = 133.12 积分。例如账户倍率为 0.75，同一请求为 99.84 积分。

创建任务时预扣积分，任务成功后按提交时的计费结果结算。后续价格或账户倍率变化不会重新计算该任务费用。

请求参数

请求体

字段	类型	必填	说明
`model`	string	是	固定为 `veo-3.1-official`
`input`	object	是	下表中的生成参数；估价使用相同的 `model` 和 `input`
`callback_url`	string	否	创建任务时可传入，用于接收完成或失败通知的公网 HTTP(S) URL

Input 参数

字段	类型	必填	说明
`prompt`	string	是	非空的视频内容描述
`mode`	string	否	`fast` 或 `quality`，默认 `fast`
`duration`	integer	否	仅支持数字 `4`、`6` 或 `8`，单位为秒，默认 `8`
`resolution`	string	否	`720p`、`1080p` 或 `4k`，默认 `720p`；也接受 `4K`
`aspect_ratio`	string	否	横屏 `16:9` 或竖屏 `9:16`，默认 `16:9`
`generate_audio`	boolean	否	是否生成音频，默认 `false`；开启后使用有音频档价格
`first_frame_image`	string	否	可访问的 HTTP(S) 图片 URL，作为视频首帧
`last_frame_image`	string	否	可访问的 HTTP(S) 图片 URL，作为视频尾帧；必须同时提供 `first_frame_image`
`negative_prompt`	string	否	描述希望避免的内容
`seed`	integer	否	随机种子，取值为 `0` 至 `4294967295` 的整数
`person_generation`	string	否	`allow_adult` 允许生成成年人，`disallow` 禁止生成人物，默认 `allow_adult`
`resize_mode`	string	否	`pad` 填充或 `crop` 裁剪，默认 `pad`；仅在提供首帧时生效
`sample_count`	integer	否	仅允许省略或数字 `1`，每个任务生成一个视频
`enhance_prompt`	boolean	否	仅允许省略或 `true`，不支持关闭提示词增强
`nsfw_checker`	boolean	否	内容审核开关，默认 `true`；仅有相应账户权限时可设为 `false`，无权限时仍保持开启

数字和布尔参数必须使用 JSON 原生类型。例如 8、1、true、false 合法，"8"、"1"、"true"、"false" 不合法；省略可选字段可使用默认值，null 不能代替省略。

图片须能直接下载，不能使用本地路径或 Base64 数据。文生视频时省略两个图片字段，无需指定生成类型。

此模型不支持 lite 模式、Auto 比例、参考素材生成或视频续写。请勿传入旧版参数 image_urls、video_urls、generation_type、seeds、watermark、enable_translation 或 n。随机种子使用单数 seed，图片使用上述首帧和尾帧字段。

生成示例

将示例中的 API Key 和图片 URL 替换为自己的值。

文生视频

以下为最小请求，使用全部默认参数，标准倍率下为 133.12 积分。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "input": {
      "prompt": "无人机缓缓飞过日落时分的山脉，柔和金色光线，电影感镜头"
    }
  }'

首帧生成

使用 first_frame_image 指定首帧。此示例生成 6 秒、1080p、无音频的竖屏视频，标准倍率下为 20.80 × 6 = 124.80 积分。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "input": {
      "prompt": "镜头缓缓推近花瓶，窗边的光影自然移动",
      "mode": "fast",
      "duration": 6,
      "resolution": "1080p",
      "aspect_ratio": "9:16",
      "generate_audio": false,
      "first_frame_image": "https://example.com/first-frame.jpg",
      "resize_mode": "crop",
      "person_generation": "disallow",
      "seed": 123456
    }
  }'

首尾帧与音频

同时传入首帧和尾帧，并用 generate_audio: true 开启音频。此示例使用 quality、4 秒、4k，标准倍率下为 124.80 × 4 = 499.20 积分。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "海边从清晨过渡到日出，镜头平稳向前，伴随轻柔海浪声",
      "mode": "quality",
      "duration": 4,
      "resolution": "4k",
      "aspect_ratio": "16:9",
      "generate_audio": true,
      "first_frame_image": "https://example.com/start.jpg",
      "last_frame_image": "https://example.com/end.jpg",
      "resize_mode": "pad",
      "negative_prompt": "模糊，镜头抖动",
      "person_generation": "disallow",
      "sample_count": 1,
      "enhance_prompt": true,
      "nsfw_checker": true
    }
  }'

估算积分

使用与生成请求相同的 model 和 input 调用估价接口。估价与生成共用参数默认值和校验规则，估价本身不扣费，也不会创建任务。

curl -X POST https://api.aivideoapi.ai/v1/estimate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-official",
    "input": {
      "prompt": "无人机缓缓飞过日落时分的山脉，柔和金色光线，电影感镜头"
    }
  }'

默认参数、标准倍率下的主要响应字段如下，其他计费明细字段已省略：

{
  "model": "veo-3.1-official",
  "credits": 133.12,
  "base_credits": 133.12,
  "multiplier": 1,
  "pricing_type": "formula"
}

base_credits 是倍率应用前的积分，credits 是应用账户倍率后的估算值。携带 API Key 会使用对应账户倍率；省略鉴权则按标准倍率估算。参数、价格和账户倍率相同时，估价与创建任务预扣积分一致；估价不会锁定价格，以提交时的结果为准。

创建响应与任务查询

创建成功返回任务 ID，并不表示视频已经生成完成：

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1"
  }
}

保存 data.taskId，用同一账户的 API Key 查询：

curl https://api.aivideoapi.ai/v1/tasks/2e723e68-7a4a-4f38-a27a-8e638f6c44a1 \
  -H "Authorization: Bearer sk-your-api-key"

pending 表示等待处理，processing 表示处理中，completed 表示完成，failed 表示失败；取消成功的任务为 cancelled。不保证每次查询都能观察到所有中间状态。

created_at 和 completed_at 使用 Unix 秒级时间戳。output.metadata 为可选信息，请以 output.urls 获取视频；已归档或清理的历史任务可能返回 output: null，建议及时保存生成结果。

处理中

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "processing",
  "model": "veo-3.1-official",
  "credits_consumed": 0,
  "created_at": 1793318400,
  "progress": null
}

credits_consumed 表示最终消耗，处理中显示 0 不代表没有预扣积分。progress: null 表示暂无百分比进度。

已完成

以下为默认请求在标准倍率下的成功响应示例，视频地址从 output.urls 读取：

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "veo-3.1-official",
  "credits_consumed": 133.12,
  "created_at": 1793318400,
  "completed_at": 1793318520,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/example.mp4"
    ]
  }
}

失败

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "veo-3.1-official",
  "credits_consumed": 0,
  "created_at": 1793318400,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed."
  }
}

确定失败的任务会退还原预扣积分，退款不会因重复查询而重复执行。已成功生成的任务不会因后续查询、回调或视频交付异常而退款。生成中遇到临时查询异常或交付延迟，请继续查询原任务，不要立即重复提交，以免创建多个独立计费任务。

回调与取消

创建时传入 callback_url，可接收任务完成或失败的 POST 通知。回调包含与查询结果一致的任务 ID、状态、最终消耗及结果或错误字段；接收端应按任务 ID 幂等处理重复通知。通知头及重试规则见回调文档。回调接收失败时，仍可查询任务获取最终结果。

已开始生成的任务不支持取消。只有尚未执行的排队任务可能通过 DELETE /v1/tasks/{taskId} 取消成功，并退还原预扣积分。可取消性以服务端响应为准，查询为 pending 不保证可取消。

无法取消时返回 HTTP 409，错误码为 task_not_cancellable；取消失败不会触发退款。更多通用错误见错误码文档。