usage

Gemini API 免费层调用

📅 2026-08-22 00:00:00 +0000 UTC 👁 3893 浏览 📂 usage

简介

Google AI Studio 提供 Gemini API 免费层，主力对话模型约每分钟 15 次请求、每天 1500 次，足够个人项目和原型验证。2026-08-22 起 Gemini 渠道正式加入 APIShare 免费渠道池：10 个对话模型进主榜（gemini-3.6-flash 为当前旗舰，gemini-3.6-flash 为官方推荐稳定款），全系统一 1M token 输入 / 64K 输出（gemma-4 双子 256K）。本篇演示文本、多模态、流式、结构化输出四种调用。

架构图

flowchart LR A[AI Studio: aistudio.google.com] --> B[Create API Key] B --> C[pip install google-genai] C --> D[Call gemini-3.6-flash] D --> E[15 RPM / 1500 req/day] E --> F[1M context window]

申请 Key

访问 https://aistudio.google.com ，用 Google 账号登录。
点击左侧 Get API Key → Create API key。
复制 AIza... 开头的字符串。

安装 SDK

pip install -U google-genai

注意：请使用新版 google-genai SDK（旧 google-generativeai 已停止演进），API 更简洁。

文本对话

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="用一句话解释什么是反向索引",
)
print(resp.text)

⚠️ thinking 注意事项：3.x 系列默认生成思维链，思考内容同样消耗输出额度。请将 max_output_tokens ≥256，否则会出现"只见思考、不见回答"的空回复。

多模态调用

from pathlib import Path
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# 图像理解
img = Path("chart.png").read_bytes()
resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents=[
        {"mime_type": "image/png", "data": img},
        "请用中文描述这张图表的关键趋势",
    ],
)
print(resp.text)

流式输出

for chunk in client.models.generate_content_stream(
    model="gemini-3.6-flash",
    contents="写一首关于秋天的五言绝句",
):
    print(chunk.text or "", end="", flush=True)
print()

结构化输出（JSON）

from pydantic import BaseModel
from google import genai

class Person(BaseModel):
    name: str
    title: str
    company: str

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="抽取：张三是阿里巴巴的高级工程师。",
    config={"response_mime_type": "application/json",
            "response_schema": Person},
)
print(resp.parsed)  # Person(name='张三', title='高级工程师', company='阿里巴巴')

安全与配额

免费层不需要绑卡，但有这些限制：

RPM：约 15（Flash 系）；gemma-4 双子更低，以控制台为准
每日请求数：约 1500（Flash 系）
输入 token 上限：1M/分钟
数据被用于训练：免费层数据可能被 Google 用于改进模型，生产环境请用付费层（Gemini API paid tier on Google Cloud）。

模型选型

当前渠道池主榜 10 个对话模型怎么选：

gemini-3.7-flash：最新旗舰，复杂任务首选；
gemini-3.6-flash：官方对新项目的推荐稳定款，21:57 实测 chat 200，高频调用首选；
gemini-3.5-flash：稳定代次；
gemini-3.1-flash-lite / -preview：轻量流水线、低成本批量处理；
gemini-flash-latest / gemini-flash-lite-latest：自动跟随最新 Flash/Lite 的别名，不想追版本号可用；
gemma-4-31b-it / gemma-4-26b-a4b-it：开源系双子（256K ctx），实测可用。

⚠️ 切勿使用 gemini-2.5-* 系列——对新用户 API Key 已 404 下线；专项任务（图像、TTS、视频、音乐、embedding）免费层配额为 0、未入池，请走付费层。

文件上传与长上下文

对于大文件（如视频、长 PDF），先用 client.files.upload() 上传，返回的 URI 在 contents 里引用，这样不用每次请求都重传。Flash 系支持最大 2GB 文件与 1M token 上下文，适合做整本书总结或长视频分析。

常见问题

429 RESOURCE_EXHAUSTED：触顶限速，等 60 秒重试或升级到付费层。
404 model not found：用了已下线型号（如 gemini-2.5-*），换 gemini-3.6-flash。
block_reason: SAFETY：触发安全过滤，调整 prompt 或降低 temperature。
想用 function calling：tools 参数传函数 schema，Gemini 会返回调用参数。

Gemini 免费层是体验多模态的最便宜路径。

最佳实践

15 RPM 是硬限：本地用 token bucket 限速到 12 RPM 留 buffer。
1M 上下文实测 800K 左右：超过 800K token 容易触发内部限制，长文档先 chunk。
图片输入直接传 bytes：SDK 支持 Path.read_bytes() 带 mime_type 直传，避免手动 base64。
旧版迁移：gemini-2.5-* 对新用户已 404 下线，更早的 gemini-1.5-*、gemini-2.0-flash 也已退出免费层清单，历史代码建议迁移至 gemini-3.6-flash 及以上。

Introduction

Google AI Studio offers a free Gemini API tier — roughly 15 requests per minute and 1500 per day on the flagship Flash models — enough for personal projects and prototyping. As of 2026-08-22, Gemini officially joined the APIShare free channel pool: 10 chat models on the main ranking (gemini-3.7-flash is the current flagship, gemini-3.6-flash is Google's recommended stable pick), all with a uniform 1M-token input / 64K output envelope (the gemma-4 twins at 256K). This article demos text, multimodal, streaming, and structured output.

Architecture

flowchart LR A[AI Studio: aistudio.google.com] --> B[Create API Key] B --> C[pip install google-genai] C --> D[Call gemini-3.6-flash] D --> E[15 RPM / 1500 req/day] E --> F[1M context window]

Get an API Key

Visit https://aistudio.google.com and sign in with a Google account.
Click Get API Key → Create API key on the left sidebar.
Copy the string starting with AIza....

Install the SDK

pip install -U google-genai

Note: use the new google-genai SDK (the old google-generativeai package is no longer evolving) — the API is cleaner.

Text Chat

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Explain inverted indexes in one sentence.",
)
print(resp.text)

⚠️ Thinking note: the 3.x family generates thinking chains by default and thinking tokens consume your output budget. Set max_output_tokens >= 256 or you may get empty replies that contain only thinking.

Multimodal Call

from pathlib import Path
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# Image understanding
img = Path("chart.png").read_bytes()
resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents=[
        {"mime_type": "image/png", "data": img},
        "Describe the key trend of this chart in one sentence.",
    ],
)
print(resp.text)

Streaming

for chunk in client.models.generate_content_stream(
    model="gemini-3.6-flash",
    contents="Write a haiku about autumn.",
):
    print(chunk.text or "", end="", flush=True)
print()

Structured Output (JSON)

from pydantic import BaseModel
from google import genai

class Person(BaseModel):
    name: str
    title: str
    company: str

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Extract: 'Alice is a Senior Engineer at Acme Corp.'",
    config={"response_mime_type": "response_mime_type": "application/json",
            "response_schema": Person},
)
print(resp.parsed)  # Person(name='Alice', title='Senior Engineer', company='Acme Corp.')

Safety and Quota

The free tier requires no credit card but has these limits:

RPM: ~15 (Flash family); lower for gemma-4 twins — check the console
Daily requests: ~1500 (Flash family)
Input tokens: 1M per minute
Training on your data: Free-tier data may be used by Google to improve models. Use the paid tier for production.

Model Selection

How to pick among the 10 chat models currently in the pool:

gemini-3.6-flash: newest flagship; first choice for complex tasks.
gemini-3.6-flash: Google's recommended stable pick for new projects; verified live at 21:57, first choice for high-frequency calls.
gemini-3.5-flash: stable generation.
gemini-3.1-flash-lite / -preview: lightweight pipelines and low-cost batch jobs.
gemini-flash-latest / gemini-flash-lite-latest: aliases that track the newest Flash/Lite if you don't want to chase version numbers.
gemma-4-31b-it / gemma-4-26b-a4b-it: open-source twins (256K ctx), verified working.

⚠️ Never use the gemini-2.5-* family — they return 404 for new users' API keys. Specialist tasks (image, TTS, video, music, embeddings) carry zero free-tier quota and are not in the pool — use the paid tier.

File Upload and Long Context

For large files (videos, long PDFs), first call client.files.upload() to upload, then reference the returned URI in contents — no need to re-upload on every request. The Flash family supports files up to 2GB and a 1M-token context window, ideal for whole-book summaries or long-video analysis.

Troubleshooting

429 RESOURCE_EXHAUSTED: Rate limit hit. Wait 60 seconds or upgrade to the paid tier.
404 model not found: You used a retired model (e.g. gemini-2.5-*). Switch to gemini-3.6-flash.
block_reason: SAFETY: Safety filter triggered. Adjust the prompt or lower temperature.
Function calling: Pass a function schema via tools; Gemini returns the call parameters.

The Gemini free tier is the cheapest way to experience multimodal AI.

Best Practices

15 RPM is a hard limit: implement a local token bucket at 12 RPM to leave buffer.
1M context actually caps around 800K: going beyond 800K tokens tends to hit internal limits; chunk long docs.
Send image bytes directly: pass Path.read_bytes() with a mime_type instead of manual base64.
Migrate legacy code: gemini-2.5-* returns 404 for new keys, and older gemini-1.5-* / gemini-2.0-flash have left the free-tier list — move to gemini-3.6-flash or newer.