名称： google-gemini-media
描述： 使用 Gemini API（Nano Banana 图像生成、Veo 视频、Gemini TTS 语音与音频理解）提供端到端的多模态媒体工作流和代码模板，涵盖“生成 + 理解”。
许可证： MIT

Gemini 多模态媒体（图像/视频/语音）技能

1. 目标与范围

本技能将 Gemini API 的六项能力整合为可复用的工作流和实现模板：

• 图像生成（Nano Banana：文生图、图生图、多轮迭代）
• 图像理解（描述/视觉问答/分类/比较、多图提示；支持内联和 Files API）
• 视频生成（Veo 3.1：文生视频、宽高比/分辨率控制、参考图像引导、首尾帧控制、视频延长、原生音频）
• 视频理解（上传/内联/YouTube URL；摘要、问答、带时间戳的证据）
• 语音生成（Gemini 原生 TTS：单说话人和多说话人；可控的风格/口音/语速/语调）
• 音频理解（上传/内联；描述、转录、时间段转录、令牌计数）

约定：本技能以官方 Google Gen AI SDK（Node.js/REST）为主线；目前仅提供 Node.js/REST 示例。如果你的项目已封装其他语言或框架，请将本技能的请求结构、模型选择和 I/O 规范映射到你的封装层。

2. 快速路由（决定使用哪项能力）

1) 是否需要生成图像？
- 需要从零生成图像或基于图像进行编辑 -> 使用 Nano Banana 图像生成（见第 5 节）

2) 是否需要理解图像？
- 需要识别、描述、问答、比较或信息提取 -> 使用 图像理解（见第 6 节）

3) 是否需要生成视频？
- 需要生成 8 秒视频（可选带原生音频） -> 使用 Veo 3.1 视频生成（见第 7 节）

4) 是否需要理解视频？
- 需要带时间戳的摘要/问答/片段提取 -> 使用 视频理解（见第 8 节）

5) 是否需要朗读文本？
- 需要可控的旁白、播客/有声书风格等 -> 使用 语音生成（TTS）（见第 9 节）

6) 是否需要理解音频？
- 需要音频描述、转录、时间段转录、令牌计数 -> 使用 音频理解（见第 10 节）

3. 统一的工程约束与 I/O 规范（必读）

3.0 先决条件（依赖项和工具）

• Node.js 18+（与你的项目版本匹配）
• 安装 SDK（示例）：

npm install @google/genai

• REST 示例仅需 curl；如需解析图像 Base64，可安装 jq（可选）。

3.1 认证与环境变量

• 将你的 API 密钥放入 GEMINI_API_KEY
• REST 请求使用 x-goog-api-key: $GEMINI_API_KEY

3.2 两种文件输入模式：内联 vs Files API

内联（嵌入字节/Base64）
- 优点：调用链短，适合小文件。
- 关键限制：总请求大小（文本提示词 + 系统指令 + 嵌入字节）通常有约 20MB 的上限。

Files API（上传后引用）
- 优点：适合大文件、重复使用同一文件或多轮对话。
- 典型流程：
1. files.upload(...)（SDK）或 POST /upload/v1beta/files（REST 可恢复上传）
2. 在 generateContent 中使用 file_data / file_uri

工程建议：实现 ensure_file_uri() 函数，当文件超过阈值（例如 10-15MB 警告）或被重复使用时，自动通过 Files API 路由。

3.3 二进制媒体输出的统一处理

• 图像：通常在响应部分中以 inline_data（Base64）形式返回；在 SDK 中使用 part.as_image() 或解码 Base64 并保存为 PNG/JPG。
• 语音（TTS）：通常返回 PCM 字节（Base64）；保存为 .pcm 或封装为 .wav（通常为 24kHz、16 位、单声道）。
• 视频（Veo）：长时间运行的异步任务；轮询操作；下载文件（或使用返回的 URI）。

4. 模型选择矩阵（按场景选择）

重要：模型名称、版本、限制和配额可能随时间变化。使用前请查阅官方文档。最后更新：2026-01-22。

4.1 图像生成（Nano Banana）

• gemini-2.5-flash-image：针对速度/吞吐量优化；适合频繁、低延迟的生成/编辑。
• gemini-3-pro-image-preview：更强的指令遵循和高保真文本渲染；更适合专业素材和复杂编辑。

4.2 通用图像/视频/音频理解

• 文档使用 gemini-3-flash-preview 进行图像、视频和音频理解（可根据质量/成本需求选择更强的模型）。

4.3 视频生成（Veo）

• 示例模型：veo-3.1-generate-preview（生成 8 秒视频并可原生生成音频）。

4.4 语音生成（TTS）

• 示例模型：gemini-2.5-flash-preview-tts（原生 TTS，目前为预览版）。

5. 图像生成（Nano Banana）

5.1 文生图

SDK（Node.js）最小模板

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-image",
  contents:
    "创作一幅在高档餐厅中、带有 Gemini 主题的纳米香蕉菜肴图片",
});

const parts = response.candidates?.[0]?.content?.parts ?? [];
for (const part of parts) {
  if (part.text) console.log(part.text);
  if (part.inlineData?.data) {
    fs.writeFileSync("out.png", Buffer.from(part.inlineData.data, "base64"));
  }
}

REST（带 imageConfig）最小模板

curl -s -X POST   "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent"   -H "x-goog-api-key: $GEMINI_API_KEY"   -H "Content-Type: application/json"   -d '{
    "contents":[{"parts":[{"text":"创作一幅在高档餐厅中、带有 Gemini 主题的纳米香蕉菜肴图片"}]}],
    "generationConfig": {"imageConfig": {"aspectRatio":"16:9"}}
  }'

REST 图像解析（Base64 解码）

curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"纳米香蕉的简约工作室产品图"}]}]}' \
  | jq -r '.candidates[0].content.parts[] | select(.inline_data) | .inline_data.data' \
  | base64 --decode > out.png

# macOS 可使用：base64 -D > out.png

5.2 图文生图

使用场景：给定一张图像，添加/移除/修改元素、改变风格、调色等。

SDK（Node.js）最小模板

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const prompt =
  "在桌子上添加一个纳米香蕉，保持光线一致，电影感色调。";
const imageBase64 = fs.readFileSync("input.png").toString("base64");

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-image",
  contents: [
    { text: prompt },
    { inlineData: { mimeType: "image/png", data: imageBase64 } },
  ],
});

const parts = response.candidates?.[0]?.content?.parts ?? [];
for (const part of parts) {
  if (part.inlineData?.data) {
    fs.writeFileSync("edited.png", Buffer.from(part.inlineData.data, "base64"));
  }
}

5.3 多轮图像迭代（多轮编辑）

最佳实践：使用聊天进行连续迭代（例如：先生成，然后“仅编辑特定区域/元素”，接着“生成相同风格的其他变体”）。
要输出混合的“文本 + 图像”结果，请将 response_modalities 设置为 ["TEXT", "IMAGE"]。

5.4 ImageConfig

你可以在 generationConfig.imageConfig 或 SDK 配置中设置：
- aspectRatio：例如 16:9、1:1。
- imageSize：例如 2K、4K（更高分辨率通常更慢/更昂贵，且模型支持可能不同）。

6. 图像理解（Image Understanding）

6.1 提供输入图像的两种方式

• 内联图像数据：适合小文件（总请求大小 < 20MB）。
• Files API 上传：更适合大文件或在多个请求中重复使用。

6.2 内联图像（Node.js）最小模板

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const imageBase64 = fs.readFileSync("image.jpg").toString("base64");

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: [
    { inlineData: { mimeType: "image/jpeg", data: imageBase64 } },
    { text: "为这张图像添加描述，并列出任何可见的品牌。" },
  ],
});

console.log(response.text);

6.3 使用 Files API 上传并引用（Node.js）最小模板

import { GoogleGenAI, createPartFromUri, createUserContent } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const uploaded = await ai.files.upload({ file: "image.jpg" });

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: createUserContent([
    createPartFromUri(uploaded.uri, uploaded.mimeType),
    "为这张图像添加描述。",
  ]),
});

console.log(response.text);

6.4 多图提示

在同一 contents 中追加多个图像作为多个 Part 条目；可以混合使用上传引用和内联字节。

7. 视频生成（Veo 3.1）

7.1 核心特性（必须了解）

• 生成 8 秒 高保真视频，可选 720p / 1080p / 4k，并支持原生音频生成（对话、环境音、音效）。
• 支持：
• 宽高比（16:9 / 9:16）
• 视频延长（延长已生成的视频；通常限制为 720p）
• 首尾帧控制（帧级控制）
• 最多 3 张参考图像（基于图像的引导）

7.2 SDK（Node.js）最小模板：异步轮询 + 下载

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const prompt =
  "一个猫宇航员在月球上行走的电影感镜头。包含细微的风声环境音。";
let operation = await ai.models.generateVideos({
  model: "veo-3.1-generate-preview",
  prompt,
  config: { resolution: "1080p" },
});

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  operation = await ai.operations.getVideosOperation({ operation });
}

const video = operation.response?.generatedVideos?.[0]?.video;
if (!video) throw new Error("未返回视频");
await ai.files.download({ file: video, downloadPath: "out.mp4" });

7.3 REST 最小模板：predictLongRunning + 轮询 + 下载

关键点：Veo REST 使用 :predictLongRunning 返回一个操作名称，然后轮询 GET /v1beta/{operation_name}；完成后，从响应中的视频 URI 下载。

7.4 常用控制（建议统一封装）

• aspectRatio："16:9" 或 "9:16"
• resolution："720p" | "1080p" | "4k"（更高分辨率通常更慢/更昂贵）
• 编写提示词时：将对话放在引号内；明确说明音效和环境音；使用电影摄影语言（机位、运动、构图、镜头效果、氛围）。
• 负面约束：如果 API 支持负面提示词字段，请使用它；否则列出你不希望看到的元素。

7.5 重要限制（需要工程回退方案）

• 延迟可能从几秒到几分钟不等；需实现超时和重试。
• 生成的视频在服务器上仅保留有限时间（请及时下载）。
• 输出包含 SynthID 水印。

轮询回退（带超时/退避）伪代码

const deadline = Date.now() + 300_000; // 5 分钟
let sleepMs = 2000;
while (!operation.done && Date.now() < deadline) {
  await new Promise((resolve) => setTimeout(resolve, sleepMs));
  sleepMs = Math.min(Math.floor(sleepMs * 1.5), 15_000);
  operation = await ai.operations.getVideosOperation({ operation });
}
if (!operation.done) throw new Error("视频生成超时");

8. 视频理解（Video Understanding）

8.1 视频输入选项

• Files API 上传：当文件 > 100MB、视频时长 > ~1 分钟或需要重复使用时推荐。
• 内联视频数据：适合小文件。
• 直接 YouTube URL：可分析公开视频。

8.2 Files API（Node.js）最小模板

import { GoogleGenAI, createPartFromUri, createUserContent } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const uploaded = await ai.files.upload({ file: "sample.mp4" });

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: createUserContent([
    createPartFromUri(uploaded.uri, uploaded.mimeType),
    "总结这个视频。为关键事件提供时间戳。",
  ]),
});

console.log(response.text);

8.3 时间戳提示策略

• 要求提供带“(分:秒)”时间戳的分段要点。
• 要求“提供带有具体时间范围的证据”，并在同一提示词中包含下游结构化提取（JSON）需求。

9. 语音生成（文本转语音，TTS）

9.1 定位

• 原生 TTS：用于“精确朗读 + 可控风格”（播客、有声书、广告旁白等）。
• 区别于 Live API：Live API 更具交互性，用于非结构化的音频/多模态对话；TTS 专注于可控的旁白。

9.2 单说话人 TTS（Node.js）最小模板

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-preview-tts",
  contents: [{ parts: [{ text: "用欢快的语气说：祝你拥有美好的一天！" }] }],
  config: {
    responseModalities: ["AUDIO"],
    speechConfig: {
      voiceConfig: {
        prebuiltVoiceConfig: { voiceName: "Kore" },
      },
    },
  },
});

const data =
  response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data ?? "";
if (!data) throw new Error("未返回音频");
fs.writeFileSync("out.pcm", Buffer.from(data, "base64"));

9.3 多说话人 TTS（最多 2 个说话人）

要求：
- 使用 multiSpeakerVoiceConfig
- 每个说话人名称必须与提示词中的对话标签匹配（例如 Joe/Jane）。

9.4 语音选项和语言

• voice_name 支持 30 种预置语音（例如 Zephyr、Puck、Charon、Kore 等）。
• 模型可自动检测输入语言，并支持 24 种语言（列表见文档）。

9.5 “导演注释”（强烈建议用于高质量语音）

为风格、语速、口音等提供可控的指导，但避免过度约束。

10. 音频理解（Audio Understanding）

10.1 典型任务

• 描述音频内容（包括非语音，如鸟鸣、警报等）
• 生成转录稿
• 转录特定时间段
• 计数令牌（用于成本估算/分段）

10.2 Files API（Node.js）最小模板

```js
import { GoogleGenAI, createPartFromUri, createUserContent }