Google Gemini Media技能使用说明

2026-03-29 新闻来源：网淘吧围观:17

电脑广告

手机广告

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

1. 目标与范围

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

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

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

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

您是否需要生成图像？

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

您需要理解图像吗？

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

您需要制作视频吗？

需要生成一段 8 秒的视频（可选择带原生音频） -> 使用Veo 3.1 视频生成（参见第 7 节）

您需要理解视频吗？

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

您需要朗读文本吗？

需要可控的旁白、播客/有声书风格等 -> 使用语音生成 (TTS)（参见第 9 节）

您需要理解音频吗？

需要音频描述、转录、时间范围转录、令牌计数 -> 使用音频理解（参见第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 文件API模式

内联模式（嵌入字节/Base64）

优点：调用链更短，适用于小文件。
关键约束：总请求大小（文本提示+系统指令+嵌入字节）通常有约20MB的上限。

文件API（先上传后引用）

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

工程建议：实现ensure_file_uri()功能，以便当文件超过阈值（例如10-15MB警告）或被重复使用时，自动通过文件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:
    "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) 最小模板

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 can use: 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 =
  "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. 图像理解

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

内联图像数据：适用于小文件（总请求大小 < 20MB）。
文件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: "Caption this image, and list any visible brands." },
  ],
});

console.log(response.text);

6.3 使用文件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),
    "Caption this image.",
  ]),
});

console.log(response.text);

6.4 多图像提示

将多个图像作为多个部分条目附加到同一个内容中；您可以混合使用上传的引用和内联字节。

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 =
  "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"
分辨率"720p" | "1080p" | "4k"（分辨率越高通常越慢/越贵）撰写提示词时：将对话放在引号内；明确标注音效和背景环境；使用电影摄影语言（机位、运镜、构图、镜头效果、氛围）。
负面约束：如果API支持负面提示词字段，请使用它；否则列出你不想看到的元素。
7.5 重要限制（需要工程备用方案）

延迟时间可能从几秒到几分钟不等；请实现超时和重试机制。

生成的视频在服务器上仅保留有限时间（请及时下载）。
输出内容包含SynthID水印。
轮询备用方案（含超时/退避）伪代码

8. 视频理解

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.1 视频输入选项

文件API上传

：当文件大于100MB、视频时长超过约1分钟，或需要重复使用时推荐使用。内联视频数据
：适用于较小文件。直接输入YouTube网址
Direct YouTube URL可以分析公开视频。

8.2 文件 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),
    "Summarize this video. Provide timestamps for key events.",
  ]),
});

console.log(response.text);

8.3 时间戳提示策略

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

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

9.1 定位

原生 TTS：适用于“精确朗读 + 可控风格”（播客、有声读物、广告配音等）。
与实时 API 的区别：实时 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: "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 文件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.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个token（每分钟约1920个token；具体数值可能变动）
单次提示的音频总时长上限为9.5小时；多声道音频会下混处理；音频将重新采样（具体参数请参阅文档）
若请求总大小超过20MB，必须使用文件API。

11. 端到端示例（组合）

示例A：图像生成 → 通过理解进行验证

使用Nano Banana生成产品图像（要求负空间、光线一致）。
利用图像理解进行自检：验证文本清晰度、品牌拼写及不安全元素。
若不满意，将生成的图像输入图文编辑流程并迭代优化。

示例B：视频生成 → 视频理解 → 旁白脚本

使用Veo生成8秒镜头（包含对话或音效）。
下载并保存（遵循保留期限规定）。
将视频上传至视频理解模块，生成分镜脚本+时间戳+旁白文本（随后输入TTS系统）。

示例C：音频理解 → 时段转录 → TTS重配音

上传会议音频并转录完整内容。
转录或总结特定时间段内容。
使用TTS生成摘要的"广播版"音频。

12. 合规与风险（必须遵守）

确保拥有上传图像/视频/音频的必要权利；不得生成侵权、欺骗性、骚扰性或有害内容。
生成的图像和视频包含SynthID水印；视频可能还受地区/人物生成限制。
生产系统必须为生成内容实施超时、重试、故障回退以及人工审核/后处理机制。

13. 快速参考（检查清单）

选择正确的模型：图像生成（Flash Image / Pro Image Preview）、视频生成（Veo 3.1）、文本转语音（Gemini 2.5 TTS）、理解任务（Gemini Flash/Pro）。
选择正确的输入模式：小文件使用内联方式；大型/需复用的文件使用Files API。
正确解析二进制输出：图像/音频通过inline_data解码；视频通过操作轮询+下载。
视频生成注意事项：设置宽高比/分辨率，并及时下载（避免链接过期）。
文本转语音注意事项：设置response_modalities=["AUDIO"]；最多2个说话人；说话人名称必须与提示词匹配。
音频理解注意事项：需要时使用countTokens；长音频需分段处理或使用Files API。

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Gcalcli技能使用说明下一篇：zhipu web search技能使用说明