用途
本技能用于指导开发者将 Google Gemini API 集成到应用中，重点强调使用当前官方 SDK @google/genai（v1.27+），而非已于 2025 年 11 月 30 日停止支持的旧版 @google/generative-ai。技能同时提供从旧 SDK 迁移的完整指南。
主要能力
文本生成与流式输出
支持基础文本生成与流式生成。SDK 方式通过 generateContent 与 generateContentStream 调用，流式可用异步迭代逐块输出；fetch 方式需调用 streamGenerateContent 端点并手动解析 SSE 格式（data: {json}），处理不完整分块、空行与 [DONE] 标记。
多模态输入
Gemini 2.5 系列支持在同一请求中混合文本、图片、视频、音频与 PDF。
- 图片：支持 JPEG、PNG、WebP、HEIC、HEIF，单张最大 20MB。
- 视频：支持 MP4、MPEG、MOV、AVI、FLV、MPG、WebM、WMV，内联数据最大 2 分钟、2GB（更大文件需用 File API）。
- 音频：支持 MP3、WAV、FLAC、AAC、OGG、OPUS，最大 20MB。
- PDF：最大 30MB，文本型 PDF 效果最佳，扫描件准确率可能较低。 可组合多个模态（如对比两张图片）于同一请求。
函数调用
支持工具调用连接外部 API。定义 functionDeclarations 后，模型可返回 functionCall，开发者执行函数并将 functionResponse 回传模型获取最终回答。支持基础与并行执行。
系统指令与多轮对话
支持系统指令设定与多轮聊天上下文管理。
思考模式与生成参数
支持思考模式配置（2.5 系列默认开启），以及 temperature、top-p、top-k、停止序列等生成参数。
进阶能力（Phase 2）
- 上下文缓存：基于 TTL 的缓存以优化成本。
- 代码执行：内置 Python 解释器与沙箱。
- Google 搜索接地：获取实时网络信息并附带引用。
使用方式
安装
正确 SDK：npm install @google/genai@1.34.0 错误（已弃用）：npm install @google/generative-ai（请勿使用）
环境配置
export GEMINI_API_KEY="..." 或创建 .env 文件写入 GEMINI_API_KEY=...
两种调用方式
- Node.js SDK（@google/genai）：类型安全、语法简洁、内置聊天辅助、自动 SSE 解析、错误处理更好；需 Node.js 或兼容运行时，包体积较大，部分边缘运行时可能不适用。适用于 Node.js 应用、Next.js Server Actions/Components。
- Fetch（直接 REST API）：适用于任意 JavaScript 环境（Cloudflare Workers、Deno、Bun、浏览器），依赖少、体积小、完全控制请求；但语法更冗长、需手动解析 SSE、无内置聊天辅助。适用于 Cloudflare Workers、浏览器客户端或轻量边缘运行时。
模型选择（2025）
- Gemini 3 系列：gemini-3-flash（GA，2025 年 12 月，1,048,576 输入 / 65,536 输出 token，快速高效，适合高吞吐、低延迟、成本敏感的生产场景）；gemini-3-pro-preview（预览版，2025 年 11 月 18 日，上下文规格待定，最强推理，预览模型无 SLA，生产环境建议用 GA 模型）。
- Gemini 2.5 系列（稳定 GA）：gemini-2.5-pro（复杂推理、代码、数学、STEM）；gemini-2.5-flash（性价比主力，大规模处理、低延迟、高并发、智能体场景）；gemini-2.5-flash-lite（成本优化、最快）。三者上下文均为 1,048,576 输入 / 65,536 输出 token，知识截止 2025 年 1 月，思考模式默认开启。
注意：Gemini 2.5 上下文为 1,048,576 token，并非 2M；仅上一代 Gemini 1.5 Pro 为 2M。Gemini 3 上下文规格待官方文档确认。
适用场景
需要在 Node.js、Next.js、Cloudflare Workers 等环境集成 Gemini 文本、多模态、函数调用、搜索接地等能力的开发项目；从旧 SDK 迁移的代码库；对成本优化（上下文缓存）与实时信息（搜索接地）有需求的场景。
限制
- 旧 SDK @google/generative-ai 已弃用，须迁移至 @google/genai。
- 预览模型无 SLA，可能随时变更或弃用。
- 内联视频限 2 分钟 / 2GB，更大文件需 File API。
- 图片、音频各限 20MB，PDF 限 30MB。
- 扫描版 PDF 识别准确率可能较低。
- 嵌入（embeddings）能力不在本技能内，需参考 google-gemini-embeddings 技能（text-embedding-004）。
- 具体收费与价格信息暂未提供。