Veo 视频生成

Veo 系列采用异步任务机制：调用提交接口返回任务 ID，客户端轮询至完成状态后提取成片下载链接。

接口基础信息

• 线路地址：https://img.mzfe.de（优化线路）或 https://img.zikl.dev（标准线路）
• 鉴权方式：Authorization: Bearer <API_KEY>
• 所属分组：Gemini（分组倍率 x0.08）
• 比例与分辨率：比例默认 16:9，视频输出分辨率统一为 720p。

---

模型与版本列表

模型名称 (Model ID)	规格档位	特点与适用场景
veo-3.1-fast	快速档	生成速度快，出片迅速，适合快速验证与日常创作（兼容 veo-3.1-fast-generate-preview）
veo-3.1-lite	轻量档	速度与画质均衡，动态自然流畅
veo-3.1-quality	画质档	旗舰高画质版本，光影与物理细节表现最佳（兼容 veo-3.1-generate-preview / veo-3.1-generate-preview-ref）

---

异步轮询流程

sequenceDiagram
    autonumber
    actor Client as 客户端
    participant API as Veo 接口服务
    Client->>API: POST /v1/videos (提交生成参数)
    API-->>Client: 返回任务 ID {"id": "xxxx", "status": "queued"}
    loop 每 5 ~ 10 秒轮询一次
        Client->>API: GET /v1/videos/{id}
        API-->>Client: 返回当前状态 (queued / in_progress / completed / failed)
    end
    Note over Client,API: 当 status == "completed" 时，从 url 字段获取成片

任务状态说明

状态码 (status)	说明	处理建议
queued	任务已加入等待队列	继续轮询
in_progress	任务正在生成中	继续轮询
completed	生成成功，已就绪	从 url 字段获取 MP4 视频直链
failed	生成失败	终止轮询，失败不消耗额度

---

05 文生视频

不传参考图，仅根据文字提示词生成全新视频。

• 请求方式：POST
• 请求路径：/v1/videos
• Content-Type：application/json

请求参数

参数	必填	类型	说明
model	是	string	可选：veo-3.1-fast（快速）、veo-3.1-lite（轻量）、veo-3.1-quality（画质），兼容 veo-3.1-fast-generate-preview、veo-3.1-generate-preview、veo-3.1-generate-preview-ref
prompt	是	string	视频画面与动态提示词（不要在提示词中写比例与时长）
duration	是	integer	时长，仅支持 4 / 6 / 8 秒（兼容字段 seconds）
aspect_ratio	否	string	画面比例："16:9" 或 "9:16"，默认 "16:9"
generate_audio	否	boolean	是否生成音频，默认 true（兼容字段 generateAudio）
negative_prompt	否	string	负向提示词（兼容字段 negativePrompt）

提示

使用模型 veo-3.1-generate-preview-ref 且不传参考图时，表现等同于普通文生视频。

请求示例

curl -X POST "https://img.mzfe.de/v1/videos" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "a paper boat sailing down a rain puddle, cinematic",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

响应与轮询示例

1. 提交成功响应

{
  "id": "xxxx",
  "status": "queued"
}

2. 发起轮询查询

curl "https://img.mzfe.de/v1/videos/{id}" \
  -H "Authorization: Bearer <API_KEY>"

3. 生成完成响应

{
  "id": "xxxx",
  "status": "completed",
  "url": "https://xxx.mp4"
}

---

06 单图生视频

上传一张图片作为首帧，驱动生成动态视频画面。

• 请求方式：POST
• 请求路径：/v1/videos
• Content-Type：application/json

请求参数

参数	必填	类型	说明
model	是	string	veo-3.1-fast-generate-preview 或 veo-3.1-generate-preview
prompt	是	string	镜头运动与动作要求（不要写比例与时长）
image_url	是	string	首帧图片：支持公网直链、Data URL 或裸 Base64（不支持 {"data":"...","mime_type":"..."} 嵌套对象）
duration	是	integer	4 / 6 / 8 秒（兼容 seconds）
aspect_ratio	否	string	"16:9" 或 "9:16"，默认 "16:9"
generate_audio	否	boolean	是否生成音频，默认 true
negative_prompt	否	string	负向提示词

请求示例

curl -X POST "https://img.mzfe.de/v1/videos" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "镜头缓缓推进,人物转头微笑",
    "duration": 4,
    "aspect_ratio": "16:9",
    "image_url": "https://example.com/first-frame.jpg"
  }'

---

07 首尾帧视频

传入两张图片生成中间过渡过程：第 1 张作为首帧，第 2 张作为尾帧。

• 请求方式：POST
• 请求路径：/v1/videos
• Content-Type：application/json

请求参数

参数	必填	类型	说明
model	是	string	veo-3.1-fast-generate-preview 或 veo-3.1-generate-preview
prompt	是	string	过渡过程与运镜要求
image_urls	是	array	包含两张图片的数组（第 1 张首帧，第 2 张尾帧）；支持公网直链、Data URL 或裸 Base64
duration	是	integer	4 / 6 / 8 秒
aspect_ratio	否	string	"16:9" 或 "9:16"，默认 "16:9"
generate_audio	否	boolean	是否生成音频，默认 true
negative_prompt	否	string	负向提示词

请求示例

curl -X POST "https://img.mzfe.de/v1/videos" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "生成自然连续的电影感过渡",
    "duration": 8,
    "aspect_ratio": "16:9",
    "image_urls": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ]
  }'

---

08 多参考图视频

使用多张参考图保持视频中的主体与场景风格高度一致，仅适用于参考模型。

• 请求方式：POST
• 请求路径：/v1/videos
• Content-Type：application/json

请求参数

参数	必填	类型	说明
model	是	string	固定为 veo-3.1-generate-preview-ref
prompt	是	string	视频主体与动态描述（不要包含比例与时长）
image_urls	是	array	参考图数组；支持公网直链、Data URL 或裸 Base64
duration	是	integer	带图时固定传 8 秒（传 4 或 6 秒将报错失败）
aspect_ratio	是	string	带图时固定传 "16:9"（传 9:16 将报错失败）
generate_audio	否	boolean	是否生成音频，默认 true
negative_prompt	否	string	负向提示词

参数限制

多参考图模式下，时长必须固定为 8 秒，比例必须为 "16:9"。若传入 4 / 6 秒或 9:16 会导致生成失败（失败不消耗额度）。

请求示例

curl -X POST "https://img.mzfe.de/v1/videos" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview-ref",
    "prompt": "保持主体和场景一致,生成电影感动态镜头",
    "duration": 8,
    "aspect_ratio": "16:9",
    "image_urls": [
      "https://example.com/1.jpg",
      "https://example.com/2.jpg",
      "https://example.com/3.jpg"
    ]
  }'