介绍
# Gemini Multimodal Media (Image/Video/Speech) Skill
## 1. 目标与范围
本技能将六种 Gemini API 能力整合为可复用的工作流和实现模板：
- 图像生成（Nano Banana：文生图、图像编辑、多轮迭代） - 图像理解（字幕/VQA/分类/比较、多图像提示；支持内联和 Files API） - 视频生成（Veo 3.1：文生视频、宽高比/分辨率控制、参考图像引导、首/尾帧、视频扩展、原生音频） - 视频理解（上传/内联/YouTube URL；摘要、问答、带时间戳的证据） - 语音生成（Gemini 原生 TTS：单说话人和多说话人；可控风格/口音/语速/语调） - 音频理解（上传/内联；描述、转录、时间范围转录、token 计数）
> 约定：本技能以官方 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) **您需要朗读文本吗？** - 需要可控的旁白、播客/有声书风格等 -> 使用 **语音生成**（见第 9 节）
6) **您需要理解音频吗？** - 需要音频描述、转录、时间范围转录、token 计数 -> 使用 **音频理解**（见第 10 节）
---
## 3. 统一工程约束与 I/O 规范（必读）
### 3.0 先决条件（依赖与工具）
- Node.js 18+（与您的项目版本匹配） - 安装 SDK（示例）： ```bash npm install @google/genai ``` - REST 示例仅需 `curl`；如果需要解析图像 Base64，请安装 `jq`（可选）。
### 3.1 身份验证与环境变量
- 将您的 API Key 放入 `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。 - **语音**：通常返回 **PCM** 字节（Base64）；保存为 `.pcm` 或封装为 `.wav`（通常为 24kHz、16-bit、单声道）。 - **视频**：长时间运行的异步任务；轮询操作；下载文件（或使用返回的 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) 最小模板** ```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: "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme", });
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）最小模板** ```bash 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":"Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"}]}], "generationConfig": {"imageConfig": {"aspectRatio":"16:9"}} }' ```
**REST 图像解析（Base64 解码）** ```bash 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":"A minimal studio product shot of a nano banana"}]}]}' \ | jq -r '.candidates[0].content.parts[] | select(.inline_data) | .inline_data.data' \ | base64 --decode > out.png
# macOS can use: base64 -D > out.png ```
### 5.2 文生图+图生图
使用场景：给定一张图像，**添加/删除/修改元素**、更改风格、调色等。
**SDK (Node.js) 最小模板** ```js import { GoogleGenAI } from "@google/genai"; import * as fs from "node:fs";
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Add a nano banana on the table, keep lighting consistent, cinematic tone."; 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）最小模板 ```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: "Caption this image, and list any visible brands." }, ], });
console.log(response.text); ```
### 6.3 使用 Files API 上传并引用（Node.js）最小模板 ```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), "Caption this image.", ]), });
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) 最小模板：异步轮询 + 下载 ```js import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "A cinematic shot of a cat astronaut walking on the moon. Include subtle wind ambience."; 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("No video returned"); 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 水印。
**轮询兜底（带超时/退避）伪代码** ```js const deadline = Date.now() + 300_000; // 5 min 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("video generation timed out"); ```
---
## 8. 视频理解（Video Understanding）
### 8.1 视频输入选项 - **Files API 上传**：推荐用于文件 > 100MB、视频时长 > ~1 分钟或需要复用的场景。 - **内联视频数据**：用于较小的文件。 - **直接 YouTube URL**：可以分析公开视频。
### 8.2 Files API (Node.js) 最小模板 ```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), "Summarize this video. Provide timestamps for key events.", ]), });
console.log(response.text); ```
### 8.3 时间戳提示策略 - 要求带有 "(mm:ss)" 时间戳的分段要点。 - 要求“提供特定时间范围的证据”，如果需要，在同一提示中包含下游结构化提取（JSON）。
---
## 9. 语音生成（Text-to-Speech，TTS）
### 9.1 定位 - 原生 TTS：用于“精确朗读 + 可控风格”（播客、有声书、广告旁白等）。 - 与 Live API 的区别：Live API 更侧重于交互式和非结构化音频/多模态对话；TTS 则专注于可控的旁白。
### 9.2 单说话人 TTS（Node.js）最小模板 ```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: "Say cheerfully: Have a wonderful day!" }] }], config: { responseModalities: ["AUDIO"], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" }, }, }, }, });
const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data ?? ""; if (!data) throw new Error("No audio returned"); 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 典型任务 - 描述音频内容（包括非语音内容，如鸟叫、警报声等） - 生成转录 - 转录特定时间范围 - 统计 token（用于成本估算/分段）
### 10.2 Files API (Node.js) 最小模板 ```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.mp3" });
const response = await ai.models.generateContent({ model: "gemini-3-flash-preview", contents: createUserContent([ "Describe this audio clip.", createPartFromUri(uploaded.uri, uploaded.mimeType), ]), });
console.log(response.text); ```
### 10.3 关键限制与工程技巧 - 支持常见格式：WAV/MP3/AIFF/AAC/OGG/FLAC。 - 音频 token 化：约 32 tokens/秒（约 1920 tokens/分钟；数值可能会变化）。 - 每个 prompt 的音频总长度上限为 9.5 小时；多通道音频会被下混；音频会被重采样（确切参数请参阅文档）。 - 如果请求总大小超过 20MB，您必须使用 Files API。
---
## 11. 端到端示例（组合）
### 示例 A：图像生成 -> 通过理解进行验证 1) 使用 Nano Banana 生成产品图像（要求留有负空间、光照一致）。 2) 使用图像理解进行自检：验证文本清晰度、品牌拼写以及不安全元素。 3) 如果不满意，将生成的图像输入到文本+图像编辑中进行迭代。
### 示例 B：视频生成 -> 视频理解 -> 解说脚本 1) 使用 Veo 生成一个 8 秒的镜头（包含对话或音效）。 2) 下载并保存（注意保留窗口期）。 3) 将视频上传至视频理解，以生成分镜脚本 + 时间戳 + 解说文案（然后输入至 TTS）。
### 示例 C：音频理解 -> 时段转录 -> TTS 重新配音 1) 上传会议音频并转录全部内容。 2) 转录或总结特定时间范围。 3) 使用 TTS 生成该摘要的“广播”版本。
---
## 12. 合规与风险（必须遵循）
- 确保您拥有上传图像/视频/音频的必要权限；不要生成侵权、欺骗性、骚扰或有害内容。 - 生成的图像和视频包含 SynthID 水印；视频可能还有基于地区/人物的生成限制。 - 生产系统必须实施超时、重试、故障回退机制，以及对生成内容的人工审查/后处理。
---
## 13. 快速参考（检查清单）
- [ ] 选择正确的模型：图像生成 (Flash Image / Pro Image Preview)、视频生成 (Veo 3.1)、TTS (Gemini 2.5 TTS)、理解 (Gemini Flash/Pro)。 - [ ] 选择正确的输入模式：小文件使用内联 (inline)；大文件或复用场景使用 Files API。 - [ ] 正确解析二进制输出：通过 inline_data 解码图像/音频；通过操作轮询 (operation polling) + 下载处理视频。 - [ ] 对于视频生成：设置 aspectRatio / resolution，并及时下载（避免过期）。 - [ ] 对于 TTS：设置 response_modalities=["AUDIO"]；最多 2 个说话人；说话人名称必须与 prompt 匹配。 - [ ] 对于音频理解：需要时使用 countTokens；分割长音频或使用 Files API。