Google AI Studio 免费额度教程：免绑卡申请 Gemini API，每日千次请求、支持 1M 上下文

Gemini API 有两套接入方式：原生 REST 接口和 OpenAI 兼容层，两者的密钥相同。原生接口的根地址是 https://generativelanguage.googleapis.com/v1beta，兼容层的 base_url 是 https://generativelanguage.googleapis.com/v1beta/openai/。模型名请在 AI Studio 控制台左侧的模型列表中查看，常用的有 gemini-2.5-flash、gemini-2.5-flash-lite，以控制台实际提供的名称和版本为准。

先配置环境变量，避免把密钥写死在代码里：

export GEMINI_API_KEY="你的密钥"

下面是一次最小可运行的原生 REST 对话补全请求，contents 里放对话轮次，parts 里放文本或多模态内容：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话解释什么是向量数据库"}]}
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

如果项目里已经在用 OpenAI SDK，只改 base_url 和模型名即可，消息结构完全兼容：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ['GEMINI_API_KEY'],
    base_url='https://generativelanguage.googleapis.com/v1beta/openai/',
)

resp = client.chat.completions.create(
    model='gemini-2.5-flash',
    messages=[{'role': 'user', 'content': '用一句话解释什么是向量数据库'}],
    temperature=0.7,
    max_tokens=512,
)
print(resp.choices[0].message.content)

关键参数说明：

• model：必填，决定走哪个免费档模型，写错或写了未开放的模型会直接返回 404 或 400。
• contents 与 messages：对话内容，原生接口用 role 加 parts，兼容层用 role 加 content；长文档分析可把整份文档放进同一轮，上下文上限约 1M token。
• generationConfig.temperature 与 maxOutputTokens：分别控制随机性与输出长度上限，摘要类任务调到 0.2～0.4，创意类调到 0.7～1.0；兼容层对应 temperature 和 max_tokens。
• 流式输出：原生接口加 ?alt=sse 查询参数，兼容层设置 stream=True，适合做打字机效果的前端。

额度耗尽或触发限流的典型表现：HTTP 429 并返回 RESOURCE_EXHAUSTED，通常说明超过了每分钟请求数或每日请求数；短时间内密集重试会持续失败。建议按以下顺序排查：

1. 确认请求头里的密钥正确、未过期、未在别处被删除，403 或 401 优先查这一步。
2. 核对模型名和路径拼写，models/ 后面的名字必须与控制台一致。
3. 打开控制台的配额页面，看当前模型是否还有剩余请求数，是否误用了需要付费档的模型。
4. 降低并发与请求频率，把批量任务改成串行或加固定间隔，并对 429 做指数退避重试。
5. 仍不够用时，把非关键任务切到 gemini-2.5-flash-lite，或压缩输入长度、减少重复请求以节省配额。