Xsir0 Gemini 多模态媒体（图像/视频/语音）Skill
1. 目标与适用范围
本 Skill 将 Gemini API 的 6 类能力聚合为一个可复用的工作流与实现模板：
- 图片生成（Nano Banana：文本生图、图文编辑、多轮迭代）
- 图片理解（caption/VQA/分类/对比，多图提示；支持内嵌与 Files API）
- 视频生成（Veo 3.1：文本生视频、纵横比/分辨率控制、参考图引导、首尾帧、视频扩展、原生音频）
- 视频理解（上传/内嵌/YouTube URL；摘要、问答、基于时间戳引用）
- 语音生成（Gemini 原生 TTS：单说话人、多说话人；风格/口音/节奏/语气可控）
- 音频理解（上传/内嵌；描述、转写、时间段转写、token 统计）
约定：本 Skill 以官方 Google Gen AI SDK（Python/REST）为主线；当前仅提供 Python/REST 示例。如你在项目中已有不同语言或框架封装，请将本 Skill 的“请求结构、模型选择与输入输出规范”映射到你的封装层。
2. 快速路由（先决定用哪个能力）
- 你要产出图片吗？
- 需要“从无到有生成图片”或“基于图编辑生成新图” → 使用 Nano Banana 图像生成（见第 5 章）
- 你要读懂图片吗？
- 需要识别、描述、问答、对比、抽取信息 → 使用 图片理解（见第 6 章）
- 你要产出视频吗？
- 需要生成 8 秒视频（可带原生音频） → 使用 Veo 3.1 视频生成（见第 7 章）
- 你要读懂视频吗？
- 需要总结/问答/抽取片段并引用时间戳 → 使用 视频理解（见第 8 章）
- 你要把文本念出来吗？
- 需要可控朗读、播客/有声书风格等 → 使用 语音生成（TTS）（见第 9 章）
- 你要读懂音频吗？
- 需要描述音频内容、转写、按时间段转写、统计 token → 使用 音频理解（见第 10 章）
3. 统一的工程约束与输入输出规范（必读）
3.0 运行前准备（依赖与工具）
- Python 3.x（与项目实际版本保持一致）
- 安装 SDK 与图像处理依赖（示例）：
pip install google-genai pillow
- REST 示例只需
curl；若要解析图片 Base64，建议安装jq（可选）。
3.1 认证与环境变量
- 建议将 API Key 放入环境变量：
GEMINI_API_KEY - REST 请求统一使用
x-goog-api-key: $GEMINI_API_KEY
3.2 两种“文件输入”方式：Inline vs Files API
Inline（内嵌字节/Base64）
- 优点：调用链短，适合小文件。
- 关键约束：总请求大小（文本提示 + 系统指令 + 内嵌字节）通常有 20MB 级别上限（图像/音频文档均提示此点）。
Files API（先上传再引用）
- 优点：适合大文件、重复使用同一文件、多轮对话。
- 典型流程：
files.upload(...)（SDK）或POST /upload/v1beta/files（REST resumable）- 在
generateContent中使用file_data/file_uri引用上传结果
技术落地建议：在工程里实现一个
ensure_file_uri()：当文件超过阈值（例如 10~15MB 预警）或被多次复用时，自动走 Files API。
3.3 输出“二进制媒体”的统一处理
- 图片：通常在响应的
parts中以inline_data（Base64）出现；SDK 中可用part.as_image()或自行 Base64 解码保存为 PNG/JPG。 - 语音（TTS）：返回的通常是 PCM 字节流（Base64）；需保存为
.pcm或封装成.wav（常用 24kHz、16-bit、mono）。 - 视频（Veo）：是 长耗时异步任务，需要轮询 operation；完成后下载文件（或通过返回的 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 文本生图（Text-to-Image）
SDK（Python）最小模板
from google import genai
client = genai.Client()
resp = client.models.generate_content(
model="gemini-2.5-flash-image",
contents=["Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"],
)
# 解析返回 parts：既可能有 text，也可能有 inline_data（图片）
for part in resp.parts:
if part.text:
print(part.text)
elif part.inline_data:
img = part.as_image()
img.save("out.png")
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":"Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"}]}],
"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":"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 可使用：base64 -D > out.png
5.2 图文编辑（Text-and-Image-to-Image）
用途：给定一张图，通过文本指令添加/删除/修改元素、变换风格、调色等。
SDK（Python）最小模板
from google import genai
from PIL import Image
client = genai.Client()
prompt = "Add a nano banana on the table, keep lighting consistent, cinematic tone."
img = Image.open("input.png")
resp = client.models.generate_content(
model="gemini-2.5-flash-image",
contents=[prompt, img],
)
for part in resp.parts:
if part.inline_data:
part.as_image().save("edited.png")
5.3 多轮图像迭代（Multi-turn editing）
最佳实践：使用 chat 进行连续迭代（比如先生成，再“只改某个区域/元素”，再“做同风格变体”）。
要输出“文本+图片”混合结果时，将 response_modalities 设置为 ['TEXT', 'IMAGE']。
5.4 图像配置（ImageConfig）
可在 generationConfig.imageConfig 或 SDK 的 config 中设置：
aspectRatio：例如16:9、1:1。imageSize：例如2K、4K（高分辨率通常更慢/更贵，且不同模型支持范围可能不同）。
6. 图片理解（Image Understanding）
6.1 输入图片的两种方式
- 内嵌图片数据：适合小文件（总请求大小 < 20MB）。
- Files API 上传：更适合大文件或在多个请求中复用图片。
6.2 内嵌图片（Python）最小模板
from google import genai
from google.genai import types
client = genai.Client()
with open("image.jpg", "rb") as f:
image_bytes = f.read()
resp = client.models.generate_content(
model="gemini-3-flash-preview",
contents=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
"Caption this image, and list any visible brands.",
],
)
print(resp.text)
6.3 Files API 上传并引用（Python）最小模板
from google import genai
client = genai.Client()
my_file = client.files.upload(file="image.jpg")
resp = client.models.generate_content(
model="gemini-3-flash-preview",
contents=[my_file, "Caption this image."],
)
print(resp.text)
6.4 多图提示
把多张图片作为多个 Part 追加到同一个 contents 中即可；可混用“上传引用”和“内嵌字节”。
7. 视频生成（Veo 3.1）
7.1 核心特点（你必须知道）
- 生成 8 秒高保真视频，可选 720p / 1080p / 4k，并支持原生生成音频（对话、环境声、音效）。
- 支持：
- 纵横比（16:9 / 9:16）
- 视频扩展（延长已生成视频；通常限制在 720p）
- 首帧/尾帧指定（frame-specific）
- 最多 3 张参考图引导（image-based direction）
7.2 SDK（Python）最小模板：异步轮询 + 下载
import time
from google import genai
from google.genai import types
client = genai.Client()
prompt = "A cinematic shot of a cat astronaut walking on the moon. Include subtle wind ambience."
op = client.models.generate_videos(
model="veo-3.1-generate-preview",
prompt=prompt,
config=types.GenerateVideosConfig(resolution="1080p"),
)
while not op.done:
time.sleep(10)
op = client.operations.get(op)
video = op.response.generated_videos[0].video
client.files.download(file=video)
video.save("out.mp4")
7.3 REST 最小模板：predictLongRunning + 轮询 + 下载
关键点：Veo 的 REST 接口通过 :predictLongRunning 返回 operation name，然后轮询 GET /v1beta/{operation_name}，done 后从响应里取视频 URI 下载。
7.4 常用控制项（建议统一封装）
aspectRatio:"16:9"或"9:16"resolution:"720p" | "1080p" | "4k"（更高分辨率通常更慢/更贵）- 写提示词时：用引号写对白；明确写 SFX 和环境声；使用影视镜头语言（机位、运动、构图、镜头效果、氛围）。
- 负向约束：若接口支持 negative prompt 字段，优先使用；否则用“列出你不想看到的元素”的方式表达。
7.5 重要限制（工程上要做兜底）
- 生成延迟可在秒级到分钟级波动；需要超时与重试策略。
- 生成视频在服务端只保留有限时间（需及时下载保存）。
- 输出会带 SynthID 水印。
轮询兜底（带超时/退避）伪代码
deadline = time.time() + 300 # 5 min
sleep_s = 2
while not op.done and time.time() < deadline:
time.sleep(sleep_s)
sleep_s = min(sleep_s * 1.5, 15)
op = client.operations.get(op)
if not op.done:
raise TimeoutError("video generation timed out")
8. 视频理解（Video Understanding）
8.1 视频输入方式
- Files API 上传视频：当文件 > 100MB、视频时长 > ~1 分钟，或需要多次复用时推荐。
- 内嵌视频数据：适用于更小文件。
- 直接传 YouTube URL：可用于公开视频分析。
8.2 Files API（Python）最小模板
from google import genai
client = genai.Client()
myfile = client.files.upload(file="sample.mp4")
resp = client.models.generate_content(
model="gemini-3-flash-preview",
contents=[myfile, "Summarize this video. Provide timestamps for key events."],
)
print(resp.text)
8.3 时间戳引用的提示词策略
- 让模型输出 “(mm:ss)” 的分段要点。
- 明确要求“引用具体时间段的证据”，并把下游结构化抽取（JSON）放在同一个提示里（如你需要）。
9. 语音生成（文本转语音，TTS）
9.1 关键定位
- 原生 TTS：用于“精确朗读文本 + 风格可控”（播客、有声书、广告配音等）。
- 与 Live API 区分：Live API 更偏交互式、非结构化音频与多模态会话；TTS 更偏“可控朗读”。
9.2 单说话人 TTS（Python）最小模板
from google import genai
from google.genai import types
import wave
def save_wav(filename: str, pcm: bytes, rate=24000, channels=1, sample_width=2):
with wave.open(filename, "wb") as wf:
wf.setnchannels(channels)
wf.setsampwidth(sample_width)
wf.setframerate(rate)
wf.writeframes(pcm)
client = genai.Client()
resp = client.models.generate_content(
model="gemini-2.5-flash-preview-tts",
contents="Say cheerfully: Have a wonderful day!",
config=types.GenerateContentConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
)
),
),
)
pcm = resp.candidates[0].content.parts[0].inline_data.data
save_wav("out.wav", pcm)
9.3 多说话人 TTS（最多 2 人）
要求：
- 使用
MultiSpeakerVoiceConfig - 每个 speaker 的名字必须与 prompt 中对话标签一致（如 Joe/Jane）。
9.4 语音选项与语言
voice_name支持 30 种预设声音（例如 Zephyr、Puck、Charon、Kore 等）。- 模型可自动检测输入语言，并支持 24 种语言（以文档列表为准）。
9.5 “导演备注”（强烈建议用于高质量配音）
为风格、节奏、口音等关键维度提供可控指令，但避免过度规定以免限制模型。
10. 音频理解（Audio Understanding）
10.1 典型任务
- 描述音频内容（含非语音：鸟鸣、警报等）
- 生成转写（transcript）
- 指定时间段转写
- 统计 token（用于成本评估/分段策略）
10.2 Files API（Python）最小模板
from google import genai
client = genai.Client()
myfile = client.files.upload(file="sample.mp3")
resp = client.models.generate_content(
model="gemini-3-flash-preview",
contents=["Describe this audio clip", myfile],
)
print(resp.text)
10.3 关键限制与工程建议
- 支持常见格式：WAV/MP3/AIFF/AAC/OGG/FLAC。
- 音频 token 化：约 32 token/秒（1 分钟约 1920 tokens，数值可能变化）。
- 单个提示内所有音频总时长上限为 9.5 小时；多声道会被合并；音频会被下采样（具体参数以文档为准）。
- 若总请求大小超过 20MB，必须走 Files API。
11. 端到端示例（组合编排）
示例 A：图片生成 → 再理解校验
- 用 Nano Banana 生成产品图（要求留白、统一光照）。
- 用图片理解模型做“自检”：确认文字是否清晰、品牌拼写是否正确、是否有违规元素。
- 若不满足：把生成图作为输入，走图文编辑再次迭代。
示例 B：视频生成 → 视频理解生成解说脚本
- 用 Veo 生成 8 秒镜头（包含对白或 SFX）。
- 下载并保存（注意保留期限）。
- 上传视频给视频理解模型生成：分镜脚本 + 时间戳 + 旁白文案（再交给 TTS）。
示例 C：音频理解 → 指定时间段转写 → TTS 重配音
- 上传会议音频，转写全文。
- 指定时间段做精细转写或摘要。
- 用 TTS 为摘要生成“播报版音频”。
12. 合规与风控（必须遵守）
- 确保你对上传的图片/视频/音频拥有必要权利；不得生成侵权、欺骗、骚扰或伤害性内容。
- 生成的图像与视频会带有 SynthID 水印；视频还可能有区域与人物生成策略限制。
- 任何生产系统需实现：超时、重试、失败降级、以及对生成内容的人工抽检/后处理。
13. 快速参考（Checklist）
- 选对模型：图像生成（Flash Image / Pro Image Preview）、视频生成（Veo 3.1）、TTS（Gemini 2.5 TTS）、理解（Gemini Flash/Pro）。
- 选对输入方式：小文件 inline；大文件/复用用 Files API。
- 正确解析二进制输出：image/audio 走 inline_data 解码；video 走 operation 轮询 + download。
- 对视频生成：设置 aspectRatio / resolution，并及时下载（避免过期）。
- 对 TTS：设置 response_modalities=["AUDIO"]；多说话人最多 2；speaker 名称与 prompt 对齐。
- 对音频理解：必要时 countTokens；长音频按策略分段或走 Files API。