Veo 视频生成 API 接口文档

平台: 魔芋AI (MoyuAI)
Base URL: https://www.moyu.info
更新日期: 2026-07-07

概述

Veo 是 Google 推出的尖端生成式视频模型，支持通过文本描述或参考图生成高质量视频（最高 1080P），具备电影级画质和叙事驱动能力。

接口特点：

兼容 OpenAI Video API 格式

异步任务模式：提交 → 轮询 → 下载

支持文生视频（Text-to-Video）与图生视频（Image-to-Video）

典型流程：

POST 提交任务 → 获取 task_id → GET 轮询状态 → completed → GET 下载视频

认证方式

所有 API 请求需在 HTTP Header 中携带 API Key：

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

API Key 可在魔芋AI控制台的「令牌」页面创建。

支持的模型

模型名称	说明
`veo-3`	Veo 3.0 标准版
`veo-3-fast`	Veo 3.0 快速版（生成速度更快）
`veo-3.1`	Veo 3.1 标准版（画质更好）
`veo-3.1-fast`	Veo 3.1 快速版（推荐，性价比高）

具体价格以控制台「模型价格」页面为准。

接口列表

1. 提交视频生成任务

创建一个新的视频生成任务。

请求

POST /v1/video/generations
POST /v1/videos              （兼容端点）

Headers

名称	类型	必填	说明
Authorization	string	✅	`Bearer sk-xxx`
Content-Type	string	✅	`application/json`

请求体 (JSON) — 所有参数均为顶层字段

字段	类型	必填	说明
`model`	string	✅	模型名称，如 `veo-3.1-fast`
`prompt`	string	✅	视频内容描述（英文效果更好）
`resolution`	string	✅	分辨率：`"720p"` 或 `"1080p"`
`aspect_ratio`	string	❌	宽高比：`"16:9"`（默认）或 `"9:16"`。其他值会被自动归一化为 `16:9`
`duration`	integer	❌	视频时长（秒）：`4`、`6`、`8`，默认 `8`
`images`	string[]	❌	参考图 URL 数组（图生视频用），只取第一个。只支持 http/https URL，不支持 base64
`metadata`	object	❌	可选的额外参数对象（见下方请求参数详解）

⚠️ resolution 为必填项，不传会返回 resolution is empty 错误。
⚠️ 1080p 分辨率时 duration 必须为 8。
⚠️ 图生视频的参考图只能用公网可访问的 URL，不支持直接上传 base64 图片数据。

文生视频请求示例

图生视频请求示例

响应

{
  "id": "57101aad-1398-4c0e-8559-e7f23b129fd3",
  "task_id": "57101aad-1398-4c0e-8559-e7f23b129fd3",
  "object": "video",
  "model": "veo-3.1-fast",
  "status": "PENDING",
  "progress": 0,
  "created_at": 0
}

响应字段说明

字段	类型	说明
`id`	string	任务唯一标识（UUID 格式，用于后续查询）
`task_id`	string	同 `id`（兼容旧接口）
`object`	string	固定为 `"video"`
`model`	string	使用的模型名称
`status`	string	任务状态
`progress`	integer	进度百分比 (0-100)
`created_at`	integer	创建时间（Unix 时间戳）

2. 查询任务状态

根据任务 ID 查询视频生成进度。

请求

GET /v1/videos/:task_id

注意：查询视频任务有两个路径，返回结构不同，不可混用：
GET /v1/videos/:task_id（本文档示例采用此路径）：返回扁平的 OpenAI 风格对象，status 为小写枚举（queued / in_progress / completed / failed）。
GET /v1/video/generations/:task_id：返回 {code, message, data} 包封结构，data 内 status 为大写枚举（QUEUED / IN_PROGRESS / SUCCESS / FAILURE 等）。
请固定使用其中一个路径并按其对应结构解析，切勿在两者间切换。

路径参数

参数	类型	必填	说明
`task_id`	string	✅	任务 ID（从提交响应的 `id` 字段获取）

请求示例

响应 - 排队/进行中

{
  "id": "57101aad-1398-4c0e-8559-e7f23b129fd3",
  "object": "video",
  "model": "",
  "status": "queued",
  "progress": 20,
  "created_at": 1719849600
}

响应 - 已完成

{
  "id": "57101aad-1398-4c0e-8559-e7f23b129fd3",
  "object": "video",
  "model": "",
  "status": "completed",
  "progress": 100,
  "created_at": 1719849600,
  "completed_at": 1719849900
}

响应 - 失败

{
  "id": "57101aad-1398-4c0e-8559-e7f23b129fd3",
  "object": "video",
  "model": "",
  "status": "failed",
  "progress": 100,
  "created_at": 1719849600,
  "error": {
    "message": "错误原因",
    "code": "error_code"
  }
}

状态值说明

状态	含义	建议操作
`queued`	排队中	继续轮询
`in_progress`	生成中	继续轮询
`completed`	已完成	可以下载
`failed`	失败	查看 error 信息

3. 下载视频内容

任务完成后，下载生成的视频文件。视频以 mp4 二进制流返回。

请求

GET /v1/videos/:task_id/content

路径参数

参数	类型	必填	说明
`task_id`	string	✅	已完成任务的 ID

请求示例

成功响应

HTTP 200

Content-Type: video/mp4

Content-Disposition: inline

Body: 视频二进制流

错误响应

HTTP Code	说明
400	任务尚未完成
404	任务不存在
502	视频获取失败（请重试）

请求参数详解

prompt 提示词最佳实践

使用英文：英文提示词效果普遍优于中文

描述具体场景：包含主体、动作、环境、光线、风格

使用质量关键词：cinematic, 4K, slow motion, professional lighting

好的示例：

A golden retriever running on a beach at sunset, cinematic quality, slow motion, volumetric lighting, shallow depth of field

差的示例：

狗在海边

resolution 分辨率

值	说明
`720p`	1280×720，生成速度较快
`1080p`	1920×1080，画质更好，耗时更长。要求 `duration` 必须为 8

aspect_ratio 宽高比

值	说明	适用场景
`16:9`	横屏（默认）	YouTube、网页播放
`9:16`	竖屏	抖音、Instagram Reels

仅支持 16:9 和 9:16。传入其他值（如 1:1、4:3）会被后端自动归一化为 16:9。

images 参考图（图生视频）

传 images: ["<url>"] 数组作为图生视频的核心视觉参考（当前取数组第一个 URL）。

只支持公网可访问的 http/https URL，不支持 base64 / data URL 直传。

如需用本地图片，请先上传到你自己的图床/OSS 获取公网 URL。

metadata 可选参数

metadata 对象用于传递以下可选参数：

字段	类型	说明
`negativePrompt`	string	反向提示词（不希望出现的元素）
`sampleCount`	integer	单次生成视频数量：`1`~`4`，默认 `1`
`enhancePrompt`	boolean	是否开启提示词自动优化，默认 `true`
`seed`	string	随机种子，范围 `0`~`4294967295`，用于固定生成结果

示例：

{
  "model": "veo-3.1",
  "prompt": "A serene lake at sunrise",
  "resolution": "1080p",
  "duration": 8,
  "metadata": {
    "negativePrompt": "blurry, low quality",
    "sampleCount": 1,
    "enhancePrompt": true
  }
}

异步工作流说明

┌────────┐         ┌────────┐         ┌────────┐
│  提交  │ ──────▶ │  轮询  │ ──────▶ │  下载  │
│  POST  │         │  GET   │ (循环)  │  GET   │
└────────┘         └────────┘         └────────┘
     │                  │                  │
     ▼                  ▼                  ▼
  返回 id          返回 status         返回 mp4

推荐轮询策略：

轮询间隔：10-15 秒

总生成时间：通常 1-3 分钟（720p fast），2-5 分钟（1080p）

超时设置：建议 10 分钟后停止轮询

自动超时机制：

提交后长时间未启动（可配置）→ 自动标记失败并退款

处理中超过配置阈值（默认 60 分钟，可在运营设置中调整）→ 自动标记失败并退款

错误处理

错误响应格式

{
  "code": "fail_to_fetch_task",
  "message": "{\"error\":{\"message\":\"具体错误\",\"type\":\"api_error\",\"code\":\"InvalidParameter\"}}",
  "data": null
}

常见错误

现象	原因	解决方法
`resolution is empty or failed`	未传 `resolution`	传入 `"resolution": "720p"` 或 `"1080p"`
`Invalid aspect ratio: 1:1`	传了不支持的宽高比	使用 `16:9` 或 `9:16`
`base64 data size ... exceeds maximum allowed size -1`	参考图传了 base64 数据	改用公网 http/https 图片 URL
HTTP 401	API Key 无效	检查 Token 是否正确
HTTP 403	额度不足 / 未授权该模型	充值或联系管理员开通
HTTP 503 `model_not_found`	模型未在令牌分组中启用	联系管理员启用模型

重试建议

错误类型	是否重试	说明
参数错误 (400)	❌	修正参数后重试
401/403	❌	认证/额度问题
429	✅	等待 5-10 秒后重试
500/502	✅	等待 3-5 秒，最多重试 2 次

计费说明

按次计费，提交任务时预扣额度

生成成功：扣除额度

生成失败/取消：自动退还预扣额度

超时未启动：系统自动退款

完整示例

Python

图生视频（Python 片段）

Node.js

cURL 一键测试

注意事项

resolution 必填：必须传 resolution（720p 或 1080p），否则接口报 resolution is empty

1080p 约束：1080p 时 duration 必须为 8

宽高比限制：只支持 16:9 / 9:16，其他值会被归一化为 16:9

参考图只支持 URL：图生视频的 images 只能传公网 http/https URL，不支持 base64

轮询频率：建议 10-15 秒一次，过于频繁可能触发限流

视频有效期：建议生成完成后尽快下载保存

Prompt 语言：推荐使用英文描述，效果显著优于中文

目录#

概述#

认证方式#

支持的模型#

接口列表#

1. 提交视频生成任务#

2. 查询任务状态#

3. 下载视频内容#

请求参数详解#

prompt 提示词最佳实践#

resolution 分辨率#

aspect_ratio 宽高比#

images 参考图（图生视频）#

metadata 可选参数#

异步工作流说明#

错误处理#

错误响应格式#

常见错误#

重试建议#

计费说明#

完整示例#

Python#

图生视频（Python 片段）#

Node.js#

cURL 一键测试#

注意事项#

目录

概述