⚡

谷歌GeminiAPI集成技能 google-gemini-api

本技能提供Google Gemini API的全面指南，涵盖从安装配置、模型选择到高级功能如多模态输入、函数调用、错误处理等，适用于开发者集成AI功能到应用中。关键词：Gemini API, AI开发, 多模态AI, 函数调用, 错误调试, SDK迁移, 文本生成, 流式处理

AI应用 0 次安装 0 次浏览 更新于 3/7/2026

名称: google-gemini-api 描述: 使用@google/genai SDK的Google Gemini API。用于多模态AI、思考模式、函数调用，或遇到SDK弃用警告、上下文错误、多模态格式错误。

关键词: gemini api, @google/genai, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, 多模态gemini, 思考模式, google ai, genai sdk, 函数调用gemini, 流式gemini, gemini视觉, gemini视频, gemini音频, gemini pdf, 系统指令, 多轮对话, 已弃用 @google/generative-ai, gemini上下文窗口, gemini模型2025, gemini 1M令牌, gemini工具使用, 并行函数调用, 组合函数调用 许可证: MIT

Google Gemini API - 完整指南

包: @google/genai@1.27.0 (⚠️ 不是 @google/generative-ai) 最后更新: 2025-11-21

⚠️ 关键SDK迁移警告

已弃用SDK: @google/generative-ai (于2025年11月30日停止支持) 当前SDK: @google/genai v1.27+

如果看到使用 @google/generative-ai 的代码，它是过时的！

加载 references/sdk-migration-guide.md 获取完整迁移步骤。

快速开始

安装

✅ 正确SDK:

bun add @google/genai@1.27.0

❌ 错误（已弃用）:

bun add @google/generative-ai  # 不要使用！

环境设置

export GEMINI_API_KEY="your-api-key"

第一个文本生成

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: '以简单术语解释量子计算'
});

console.log(response.text);

查看完整模板: templates/basic-usage.ts

当前模型（2025）

gemini-2.5-flash ⭐ 推荐

  • 最佳用于: 通用AI、高流量生产、智能体工作流
  • 输入令牌: 1,048,576 (1M，不是2M！)
  • 输出令牌: 65,536
  • 速率限制（免费）: 10 RPM, 250k TPM
  • 成本: 输入 $0.075/1M 令牌, 输出 $0.30/1M 令牌
  • 功能: 思考模式、函数调用、多模态、流式

gemini-2.5-pro

  • 最佳用于: 复杂推理、代码生成、数学/STEM
  • 输入令牌: 1,048,576
  • 输出令牌: 65,536
  • 速率限制（免费）: 5 RPM, 125k TPM
  • 成本: 输入 $1.25/1M 令牌, 输出 $5/1M 令牌

gemini-2.5-flash-lite

  • 最佳用于: 高流量、低延迟、成本关键任务
  • 输入令牌: 1,048,576
  • 输出令牌: 65,536
  • 速率限制（免费）: 15 RPM, 250k TPM
  • 成本: 输入 $0.01/1M 令牌, 输出 $0.04/1M 令牌
  • ⚠️ 限制: 不支持函数调用或代码执行

⚠️ 常见错误: 声称Gemini 2.5有2M令牌。它没有。它是1,048,576 (1M)。

加载 references/models-guide.md 获取详细模型比较和选择标准。

文本生成

基本生成

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '写一首关于编程的俳句'
});

console.log(response.text);

带配置

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '解释AI',
  generationConfig: {
    temperature: 0.7,        // 0.0-2.0, 默认 1.0
    topP: 0.95,             // 0.0-1.0
    topK: 40,               // 1-100
    maxOutputTokens: 1024,
    stopSequences: ['END']
  }
});

加载 references/generation-config.md 获取完整参数参考和调优指导。

流式

const stream = await ai.models.generateContentStream({
  model: 'gemini-2.5-flash',
  contents: '写一个长故事'
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text);
}

加载 references/streaming-patterns.md 获取Fetch/SSE实现模式（Cloudflare Workers）。

多模态输入

图像

const imageData = Buffer.from(imageBytes).toString('base64');

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: [
    { text: '这张图片里有什么？' },
    {
      inlineData: {
        mimeType: 'image/jpeg',  // 或 image/png, image/webp
        data: imageData
      }
    }
  ]
});

视频、音频、PDF

相同模式 - 使用适当的 mimeType:

  • 视频: video/mp4, video/mpeg, video/mov
  • 音频: audio/wav, audio/mp3, audio/flac
  • PDF: application/pdf

加载 references/multimodal-guide.md 获取格式规范、大小限制和最佳实践。

函数调用

基本模式

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '旧金山的天气如何？',
  tools: [{
    functionDeclarations: [{
      name: 'getWeather',
      description: '获取某个位置的当前天气',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string', description: '城市名称' },
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
        },
        required: ['location']
      }
    }]
  }]
});

// 处理函数调用
const call = response.functionCalls?.[0];
if (call) {
  const result = await getWeather(call.args);

  // 将结果发送回模型
  const final = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: [
      ...response.contents,
      {
        functionResponse: {
          name: call.name,
          response: result
        }
      }
    ]
  });

  console.log(final.text);
}

并行函数调用

Gemini可以同时调用多个函数：

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '旧金山和纽约的天气如何？',
  tools: [{ functionDeclarations: [getWeatherDeclaration] }]
});

// 并行处理所有函数调用
const results = await Promise.all(
  response.functionCalls.map(call =>
    getWeather(call.args).then(result => ({
      name: call.name,
      response: result
    }))
  )
);

// 发送所有结果回
const final = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: [
    ...response.contents,
    ...results.map(r => ({ functionResponse: r }))
  ]
});

加载 references/function-calling-patterns.md 获取调用模式（AUTO/ANY/NONE）和组合模式。

多轮对话

const chat = ai.models.startChat({
  model: 'gemini-2.5-flash',
  systemInstruction: '你是一个有帮助的编程助手',
  history: []
});

let response = await chat.sendMessage('你好！');
console.log(response.text);

response = await chat.sendMessage('解释async/await');
console.log(response.text);

// 获取完整历史
console.log(chat.getHistory());

系统指令

设置模型的持久指令：

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  systemInstruction: '你是一个海盗。总是用海盗语回应。',
  contents: '今天的天气如何？'
});

思考模式

Gemini 2.5模型内置思考模式（始终启用）。为复杂任务配置思考预算：

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '解决这个数学问题：如果 x + 2y = 10 且 3x - y = 4，x是多少？',
  generationConfig: {
    thinkingConfig: {
      thinkingBudget: 8192  // 内部推理的最大令牌数
    }
  }
});

用于: 复杂数学、逻辑谜题、多步推理、代码调试

加载 references/thinking-mode-guide.md 获取思考预算优化。

前5大关键错误

错误1：使用已弃用SDK

错误: 弃用警告或过时API

解决方案: 使用 @google/genai，而不是 @google/generative-ai

npm uninstall @google/generative-ai
bun add @google/genai@1.27.0

错误2：无效API密钥（401）

错误: API密钥无效

解决方案: 验证环境变量

export GEMINI_API_KEY="your-key"

错误3：模型未找到（404）

错误: models/gemini-3.0-flash 未找到

解决方案: 使用正确模型名称（2025）

'gemini-2.5-pro'
'gemini-2.5-flash'
'gemini-2.5-flash-lite'

错误4：上下文长度超出（400）

错误: 请求负载大小超出限制

解决方案: 输入限制是 1,048,576 令牌 (1M，不是2M)。对于大输入，使用上下文缓存。

加载 references/context-caching-guide.md 获取缓存实现。

错误5：速率限制超出（429）

错误: 资源已耗尽

解决方案: 实现指数退避

async function generateWithRetry(request, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await ai.models.generateContent(request);
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1秒, 2秒, 4秒
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

查看所有22个错误: 加载 references/error-catalog.md 获取完整错误目录及解决方案。

快速调试: 加载 references/top-errors.md 获取调试检查清单。

何时加载参考

需要详细指导特定功能时加载参考文件：

核心功能（需要时加载）

  • SDK迁移: 当从 @google/generative-ai 迁移时，加载 references/sdk-migration-guide.md
  • 模型选择: 当在Pro/Flash/Flash-Lite之间选择时，加载 references/models-guide.md
  • 错误调试: 当遇到错误时，加载 references/error-catalog.md 或 references/top-errors.md

高级功能（实现时加载）

  • 上下文缓存: 当为大/重复输入实现成本优化时，加载 references/context-caching-guide.md
  • 代码执行: 当启用Python代码执行进行计算/分析时，加载 references/code-execution-patterns.md
  • 基础（Google搜索）: 当连接模型到实时网络信息时，加载 references/grounding-guide.md
  • 流式实现: 当为Cloudflare Workers实现SSE解析时，加载 references/streaming-patterns.md
  • 函数调用模式: 当使用AUTO/ANY/NONE模式或组合模式时，加载 references/function-calling-patterns.md
  • 多模态格式: 当处理图像/视频/音频/PDF时（格式规范、大小限制），加载 references/multimodal-guide.md
  • 生成调优: 当微调temperature/topP/topK参数时，加载 references/generation-config.md
  • 思考模式配置: 当为复杂推理优化思考预算时，加载 references/thinking-mode-guide.md

一般规则: SKILL.md提供快速开始和顶级错误。加载参考以深入了解、详细模式或解决特定功能问题。

捆绑资源

模板 (templates/):

  • basic-usage.ts - 所有功能的完整示例（133行）

参考 (references/):

  • error-catalog.md - 所有7个文档化错误及解决方案（231行）
  • top-errors.md - 22个常见错误的快速调试检查清单（305行）
  • sdk-migration-guide.md - 从已弃用SDK的完整迁移（236行）
  • models-guide.md - 详细模型比较和选择指南（247行）
  • context-caching-guide.md - 使用缓存的成本优化（374行）
  • code-execution-patterns.md - Python代码执行指南（482行）
  • grounding-guide.md - Google搜索集成（603行）
  • streaming-patterns.md - Cloudflare Workers的SSE实现（82行）
  • function-calling-patterns.md - 高级函数调用模式（60行）
  • multimodal-guide.md - 格式规范和限制（59行）
  • generation-config.md - 参数调优参考（58行）
  • thinking-mode-guide.md - 思考预算优化（60行）

与其他技能集成

本技能与以下技能配合良好：

  • cloudflare-worker-base → 部署到Cloudflare Workers
  • ai-sdk-core → Vercel AI SDK集成
  • openai-api → 多提供商AI设置
  • google-gemini-embeddings → 文本嵌入

额外资源

官方文档:

生产测试: AI聊天机器人、内容生成、多模态分析 最后更新: 2025-10-25 令牌节省: ~65%（减少API文档 + 示例）