google-gemini-api

用途

本技能用于指导开发者正确集成 Google Gemini API。其核心价值在于强调 SDK 迁移：已弃用的 @google/generative-ai 将于 2025 年 11 月 30 日停止服务，当前应使用 @google/genai v1.27+。技能提供完整的迁移指南，并纠正常见错误（例如误认为 Gemini 2.5 支持 2M token 上下文，实际为 1,048,576 输入 token）。

主要能力

Phase 1 核心功能：

文本生成（基础与流式）
多模态输入：图片、视频、音频、PDF
函数调用（基础与并行执行）
系统指令与多轮对话
思考模式配置
生成参数（temperature、top-p、top-k、停止序列）
Node.js SDK 与 fetch 两种调用方式

Phase 2 进阶功能：

上下文缓存（基于 TTL 的成本优化）
代码执行（内置 Python 解释器与沙箱）
Google 搜索接地（实时网络信息与引用）

嵌入功能单独提供，见 google-gemini-embeddings 技能（text-embedding-004）。

使用方式

安装正确 SDK：

npm install @google/genai@1.27.0

错误（已弃用，请勿使用）：

npm install @google/generative-ai

环境变量设置：

export GEMINI_API_KEY="..."

或创建 .env 文件：

GEMINI_API_KEY=...

Node.js SDK 基础文本生成示例：

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

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

const response = await ai.models.generateContent({ model: 'gemini-2.5-flash', contents: 'Explain quantum computing in simple terms' });

console.log(response.text);

Fetch（Cloudflare Workers）示例：

const response = await fetch( https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-goog-api-key': env.GEMINI_API_KEY, }, body: JSON.stringify({ contents: [{ parts: [{ text: 'Explain quantum computing in simple terms' }] }] }), } );

const data = await response.json(); console.log(data.candidates[0].content.parts[0].text);

流式输出使用 streamGenerateContent 端点，需解析 SSE 格式（data: {json}），处理缓冲区中的不完整分块，跳过空行与 [DONE] 标记。

多模态输入支持在同一请求中组合文本、图片、视频、音频、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 效果最佳。

函数调用通过 functionDeclarations 定义工具，模型返回 functionCall 后由开发者执行并将 functionResponse 回传。支持并行函数调用。

适用场景

构建 Node.js 应用、Next.js Server Actions/Components
部署到 Cloudflare Workers、Deno、Bun、浏览器等边缘运行时（使用 fetch 方式）
需要多模态理解、函数调用、流式输出的 AI 应用
需要成本优化（上下文缓存）或实时信息（Google 搜索接地）的场景

模型与限制

Gemini 3 系列（预览，2025 年 11 月）：gemini-3-pro-preview，上下文规格待官方文档，建议评估使用，生产环境可考虑 gemini-2.5-pro。

Gemini 2.5 系列（稳定）：

gemini-2.5-pro：1,048,576 输入 token / 65,536 输出 token，适合代码、数学、STEM、复杂推理，知识截止 2025 年 1 月
gemini-2.5-flash：同上下文，最佳性价比，适合大规模处理、低延迟、高并发、智能体场景
gemini-2.5-flash-lite：同上下文，成本优化、速度最快，适合高吞吐、成本敏感应用

所有 2.5 模型默认开启思考模式，均支持函数调用、多模态、流式、系统指令。

注意：Gemini 2.5 上下文为 1,048,576 输入 token，并非 2M；仅上一代 Gemini 1.5 Pro 支持 2M。Gemini 3 上下文规格暂未提供。

技能还包含错误处理、速率限制、SDK 迁移指南与生产最佳实践等参考内容。

技能介绍

用途

主要能力

使用方式

适用场景

模型与限制