Gemini API 调用指南 | 错误处理大全

Gemini API基础调用

Gemini API是Google提供的先进AI服务，支持文本、图像等多种输入方式。以下是基础调用的代码示例和说明。

1. 环境设置

首先需要安装必要的SDK并设置API密钥：

npm install @google/generative-ai

// 初始化Gemini客户端
const { GoogleGenerativeAI } = require("@google/generative-ai");

// 使用您的API密钥
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

2. 基本调用示例

简单的文本生成调用：

async function generateText(prompt) {
  // 获取模型实例
  const model = genAI.getGenerativeModel({ model: "gemini-pro" });
  
  // 生成内容
  const result = await model.generateContent(prompt);
  const response = await result.response;
  
  return response.text();
}

// 使用示例
generateText("写一篇关于人工智能的文章")
  .then(text => console.log(text))
  .catch(error => console.error("Error:", error));

高级调用参数

温度参数 (temperature)

控制输出随机性 (0-1)

model.generateContent({ temperature: 0.5 })

令牌限制 (maxOutputTokens)

限制响应长度

model.generateContent({ maxOutputTokens: 256 })

多轮对话

保持对话上下文

model.startChat({ history: [...] })

这些参数可以根据您的需求组合使用以获得最佳效果

API认证与授权

正确配置认证是使用Gemini API的关键。以下是认证流程和注意事项。

API密钥获取

从Google AI Studio获取您的API密钥

访问 Google AI Studio
登录您的Google账号
导航至API密钥部分
创建新密钥
安全存储您的密钥

切勿将API密钥直接存储在客户端代码中

密钥安全最佳实践

保护您的API密钥免受泄露

使用环境变量存储密钥

限制API密钥的访问范围

设置使用配额和API限制

定期轮换API密钥

常见认证错误

错误码	含义	解决方案
401 Unauthorized	无效的API密钥	检查密钥是否正确，或生成新的API密钥
403 Forbidden	API访问权限不足	确保项目已启用Gemini API，核对IAM权限
429 Too Many Requests	超出配额限制	检查配额使用情况，考虑升级计划或调整调用频率

全面错误处理指南

Gemini API可能返回多种类型的错误，合理的错误处理可以提高应用程序的稳定性。

错误分类与处理

1. 客户端错误 (4xx)

400 Bad Request

请求格式不正确或缺少必要参数

常见原因:

缺少必填字段
无效的参数值
JSON格式错误

403 Permission Denied

客户端权限不足

解决方案:

检查API密钥是否正确配置
确保项目有足够的权限
核对IAM角色分配

2. 服务器错误 (5xx)

503 Service Unavailable

服务器暂时无法处理请求

处理建议:

实现指数退避重试机制
检查Google Cloud状态页面是否有服务中断
稍后重试

3. 内容生成错误

内容安全过滤

请求内容违反了安全策略

处理方式:

检查提示词是否包含不当内容
调整内容重试
使用内容安全设置（如果可用）

生成超时

响应生成超出时间限制

解决方案:

简化提示词或减少输出长度
增加超时设置
分割复杂请求为多个简单请求

错误处理代码示例

基础错误处理

async function safeGenerate(prompt) {
  try {
    const model = genAI.getGenerativeModel({ model: "gemini-pro" });
    const result = await model.generateContent(prompt);
    return await result.response.text();
  } catch (error) {
    console.error('API调用失败:', error);
    
    // 分类处理不同错误
    if (error.response) {
      // API响应错误
      const { status, statusText } = error.response;
      
      switch (status) {
        case 400:
          throw new Error(`请求无效: ${statusText}`);
        case 401:
          throw new Error('认证失败，请检查API密钥');
        case 403:
          throw new Error('权限不足，请核对项目权限');
        case 429:
          throw new Error('请求过于频繁，请稍后再试');
        case 500:
          throw new Error('服务器内部错误');
        default:
          throw new Error(`未知API错误: ${status} - ${statusText}`);
      }
    } else if (error.request) {
      // 无响应错误
      throw new Error('无法连接到API服务，请检查网络');
    } else {
      // 其他错误
      throw new Error('未知错误: ' + error.message);
    }
  }
}

带重试机制的处理

async function generateWithRetry(prompt, retries = 3) {
  const baseDelay = 1000; // 初始延迟1秒
  
  for (let i = 0; i < retries; i++) {
    try {
      return await safeGenerate(prompt);
    } catch (error) {
      // 仅在特定错误时重试
      if (error.message.includes('请求过于频繁') || 
          error.message.includes('服务器内部错误') ||
          error.message.includes('无法连接到API')) {
        
        // 指数退避
        const delay = baseDelay * Math.pow(2, i) + Math.random() * 1000;
        console.warn(`尝试${i + 1}/${retries}失败，${delay}ms后重试...`);
        
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error; // 其他错误直接抛出
    }
  }
  throw new Error(`超出最大重试次数(${retries})`);
}

最佳实践与优化建议

遵循这些最佳实践可以显著提高您的Gemini API集成质量和性能。

性能优化

使用流式响应处理大文本输出，降低内存占用和延迟
合理设置maxOutputTokens以避免生成不必要的长文本
批处理多个请求以提高吞吐量
实现本地缓存机制以减少重复API调用

安全建议

对所有用户输入进行清理，防止提示注入攻击
实施速率限制防止滥用您的API集成
定期审计API使用情况和权限设置
考虑内容审核，特别是在用户生成内容中

API实时诊断工具

输入您的API请求，我们将帮助诊断潜在问题

实际案例研究

了解其他开发人员在使用Gemini API时遇到的问题及解决方案。

案例1：内容安全限制问题

问题描述

开发者尝试使用API生成医疗建议内容时频繁遇到内容安全限制错误（403）。

根本原因

某些特定医疗术语和组合触发了Gemini的安全过滤机制，尽管内容本身无害。

解决方案

重构提示词，使用更学术和中性的表达方式
添加内容安全上下文标记
将长请求分解为多个更简单的步骤
为敏感词汇申请内容审核例外

案例2：API配额和缓存策略

问题描述

电商网站的产品描述生成功能在大流量时段经常遇到429（过多请求）错误，影响用户体验。

根本原因

相似的请求频繁发送给API，未利用缓存，导致快速消耗配额。

解决方案

实现本地缓存层存储常见产品描述
对相似产品使用模板化响应而非全新生成
设置备用内容生成方案（如预先生成内容）
申请提高API配额并监控使用情况

掌握Gemini API调用全面错误处理指南

Gemini API基础调用

1. 环境设置

2. 基本调用示例

高级调用参数

温度参数 (temperature)

令牌限制 (maxOutputTokens)

多轮对话

API认证与授权

API密钥获取

密钥安全最佳实践

常见认证错误

全面错误处理指南

错误分类与处理

1. 客户端错误 (4xx)

400 Bad Request

403 Permission Denied

2. 服务器错误 (5xx)

503 Service Unavailable

3. 内容生成错误

内容安全过滤

生成超时

错误处理代码示例

基础错误处理

带重试机制的处理

最佳实践与优化建议

性能优化

安全建议

API实时诊断工具

诊断结果

实际案例研究

案例1：内容安全限制问题

问题描述

根本原因

解决方案

案例2：API配额和缓存策略

问题描述

根本原因

解决方案

掌握Gemini API调用 全面错误处理指南

Gemini API基础调用

1. 环境设置

2. 基本调用示例

高级调用参数

温度参数 (temperature)

令牌限制 (maxOutputTokens)

多轮对话

API认证与授权

API密钥获取

密钥安全最佳实践

常见认证错误

全面错误处理指南

错误分类与处理

1. 客户端错误 (4xx)

400 Bad Request

403 Permission Denied

2. 服务器错误 (5xx)

503 Service Unavailable

3. 内容生成错误

内容安全过滤

生成超时

错误处理代码示例

基础错误处理

带重试机制的处理

最佳实践与优化建议

性能优化

安全建议

API实时诊断工具

诊断结果

实际案例研究

案例1：内容安全限制问题

问题描述

根本原因

解决方案

案例2：API配额和缓存策略

问题描述

根本原因

解决方案

掌握Gemini API调用全面错误处理指南

目录导航

Gemini API 调用指南 | 错误处理大全

预览结果：