Gemini API怎么用？从API密钥到多轮对话与结构化输出指南

Gemini API的基本流程可以概括为：准备开发者入口和API密钥，提交包含消息内容的请求，读取候选结果，再根据业务需要校验和保存响应。示例中的模型名称使用占位符，实际使用时应填写你在当前开发者文档和项目中可用的模型名称，不要直接复制过时配置。

一、创建并保存API密钥

可以从Google AI Studio进入Gemini API相关页面，创建或管理API密钥。密钥只用于服务端配置，不应写入网页前端、移动端安装包、公开代码仓库或截图中。推荐在本地或部署平台配置环境变量，例如将密钥保存为GEMINI_API_KEY，程序通过环境变量读取，而不是把真实值硬编码进源文件。

如果使用命令行，可以先设置环境变量，再让程序读取它。生产环境还应限制日志内容，避免把请求头、完整响应或包含个人信息的提示词写入普通日志。

二、最小文本请求

Gemini API的请求通常包含一个contents数组。每条消息包含角色和一个或多个文本部分；响应中则从候选结果的内容部分读取生成文本。下面是使用Python标准HTTP库思路的简化示例，模型名称、接口版本和超时时间应以当前官方文档为准：

import os, requests
api_key = os.environ["GEMINI_API_KEY"]
model = "MODEL_NAME"
url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={api_key}"
body = {"contents": [{"role": "user", "parts": [{"text": "请用两句话介绍夏季防晒。"}]}]}
response = requests.post(url, json=body, timeout=30)
response.raise_for_status()
data = response.json()
text = data["candidates"][0]["content"]["parts"][0]["text"]

实际程序不要假设候选结果始终存在。应先检查HTTP状态、响应JSON是否可解析、候选数组是否为空，以及内容部分是否包含文本。模型可能返回其他完成状态，业务代码需要根据接口返回结构进行兼容处理。

三、多轮对话的消息历史

API调用本身通常是无状态的。要让模型理解前文，应用需要在下一次请求中重新提交必要的消息历史。例如：

body = {"contents": [
{"role": "user", "parts": [{"text": "我想规划一日游。"}]},
{"role": "model", "parts": [{"text": "可以，请告诉我城市和兴趣。"}]},
{"role": "user", "parts": [{"text": "我在杭州，喜欢历史。"}]}

]}

应用应自行保存会话ID、用户消息和模型回复，并按长度或令牌预算截断旧历史。不要无限追加对话，也不要把不同用户的历史混在同一个会话中。若历史包含隐私信息，应先脱敏，并设置合理的保存期限。

四、普通文本与结构化输出

普通文本适合直接展示给用户，但不适合直接作为数据库记录或业务指令。需要固定字段时，可以要求接口返回JSON，并在客户端执行JSON解析和字段校验。部分可用接口支持通过生成配置指定responseMimeType为application/json，并进一步提供responseSchema，例如定义name、category和confidence等字段。

概念示例：responseGenerationConfig = {"responseMimeType": "application/json", "responseSchema": {"type": "OBJECT", "properties": {"question": {"type": "STRING"}, "category": {"type": "STRING"}, "answer": {"type": "STRING"}}, "required": ["question", "category", "answer"]}}

然后在提示词中说明：把用户问题整理为上述字段，只返回对象，不添加解释。拿到响应后仍然要执行JSON解析、必填字段检查、类型检查和枚举值检查。Schema约束能降低格式偏差，但在复杂提示、内容冲突或接口能力不匹配时，不能保证百分之百符合预期；失败时应记录原因并走人工或补救流程。

五、超时、错误和限流

• 超时：为HTTP请求设置有限超时时间，避免工作线程长期占用；长任务可使用队列和异步处理。
• 400类错误：通常先检查请求JSON、角色顺序、字段类型和模型配置，不要盲目重试。
• 401或403：检查密钥、项目权限、接口配置和可用范围，并确认没有把密钥写错环境。
• 429限流：降低并发，按照响应提供的信息或指数退避等待后重试，同时设置最大重试次数。
• 5xx错误：可以进行有限次指数退避重试，并保留请求追踪信息；多次失败后应返回可理解的降级提示。

重试必须避免重复写入。对于会产生订单、消息或其他副作用的操作，应使用业务请求ID做幂等控制。重试日志可记录状态码、耗时和追踪ID，但不应记录API密钥或完整敏感内容。

六、一个小型数据抽取流程

例如客服系统收到“我的耳机左侧没有声音，购买不到两个月”后，可要求模型输出question、category、purchase_period和suggested_reply四个字段。程序先提交文本和Schema约束，再校验category是否属于预设分类，最后把suggested_reply作为客服草稿，而不是直接发送。原始响应、解析结果和校验失败原因可按脱敏规则保存，方便人工复核。

如果发现密钥泄露，应立即在密钥管理页面撤销或删除旧密钥，生成新密钥并更新部署环境，同时检查访问日志和费用异常。不要只删除公开仓库中的文件，因为历史提交可能仍然保留密钥。把密钥管理、响应校验、超时控制和有限重试一起做好，才是可维护的Gemini API调用流程。