AI Studio 中文指南

Appearance

Gemini API 完整开发实战：API Key 申请、Python/JS SDK 调用、流式传输与函数调用 ​

ℹ️30秒极速接入指南 (TL;DR Answer-First)
如何 3 步完成 Gemini API 快速调用？
1. 获取密钥：登录 Google AI Studio，点击左侧导航栏的 「Get API key」，创建或选择一个 Google Cloud 项目并生成全新的 API Key。
2. 安装官方依赖：在终端执行 pip install google-generativeai（Python）或 npm install @google/genai（Node.js）。
3. 发起首个调用：配置环境变量 export GEMINI_API_KEY="YOUR_API_KEY"，初始化 genai.GenerativeModel('gemini-1.5-flash') 并调用 generate_content("Hello Gemini!") 即可获得响应。
⚠️非官方与安全凭证警告
本站为独立第三方技术社区，非 Google 官方。请在测试代码中统一使用 YOUR_API_KEY 占位符，严禁将包含真实 API 密钥的配置文件公开暴露或提交至公共 Git 仓库。

目录导航 ​

一、API Key 申请流程与安全规范 ​

Google 将 Gemini 的 API 密钥生成流程极大简化，无需预先填写繁琐的企业资质审核：

STEP 1

在 AI Studio 创建 API Key

访问 Google AI Studio API Key 管理页面。点击 「Create API key」 按钮。你可以选择将 Key 绑定到已有的 Google Cloud Project，或者让系统为你自动创建一个默认项目。
STEP 2

配置本地环境变量

获取到以 AIzaSy... 开头的密钥字符串后，将其保存至系统的环境变量中，避免硬编码：
📄终端配置环境变量
BASH
bash
# macOS / Linux (写入 ~/.bashrc 或 ~/.zshrc)
export GEMINI_API_KEY="YOUR_API_KEY"

# Windows PowerShell (当前会话生效)
$env:GEMINI_API_KEY="YOUR_API_KEY"

# Windows 系统级持久生效命令
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'YOUR_API_KEY', 'User')

二、官方 SDK 安装与环境配置 ​

Google 官方维护了多语言版本的原生 SDK，底层深度封装了 Token 计数、重试及多模态二进制编码：

2.1 Python SDK ​

bash
pip install google-generativeai

2.2 JavaScript / TypeScript SDK ​

bash
npm install @google/genai

三、核心调用范例：文本、多模态与流式输出 ​

3.1 经典 Python 同步生成 ​

📄quickstart.py
PYTHON
python
import os
import google.generativeai as genai

# 读取环境变量中的 API Key
api_key = os.getenv('GEMINI_API_KEY', 'YOUR_API_KEY')
genai.configure(api_key=api_key)

# 实例化轻量高效的 Flash 模型
model = genai.GenerativeModel('gemini-1.5-flash')

# 同步生成文本内容
response = model.generate_content('请用通俗幽默的语言解释什么是量子纠缠？')
print(response.text)

3.2 图像多模态输入调用 ​

你可以直接传递 Pillow 图像对象或原始二进制字节给模型：

📄vision_demo.py
PYTHON
python
import os
import PIL.Image
import google.generativeai as genai

genai.configure(api_key=os.getenv('GEMINI_API_KEY', 'YOUR_API_KEY'))
model = genai.GenerativeModel('gemini-1.5-flash')

# 读取本地图片
img = PIL.Image.open('invoice.jpg')

# 传入混合多模态提示词
response = model.generate_content([
    '请分析这张发票图片，提取出：发票代码、开票金额、开票日期，并以 JSON 格式返回。',
    img
])

print(response.text)

四、Streaming 流式响应实现机制 ​

在 Web 前端开发中，等待整个大段落生成完成往往需要数秒。利用流式响应（Streaming），服务器能够以 Server-Sent Events (SSE) 的方式将刚生成的 Token 即刻推送到客户端，呈现流畅的打字机视觉效果：

📄stream_demo.py
PYTHON
python
import os
import google.generativeai as genai

genai.configure(api_key=os.getenv('GEMINI_API_KEY', 'YOUR_API_KEY'))
model = genai.GenerativeModel('gemini-1.5-flash')

# 开启 stream=True 流式生成
response = model.generate_content(
    '请写一篇关于火星殖民地未来 100 年演化史的技术畅想，字数 1000 字左右。',
    stream=True
)

for chunk in response:
    # 实时打印每个下发的 Token 分块
    print(chunk.text, end='', flush=True)

五、Function Calling（函数/工具调用）实战 ​

Gemini 具备极其强大的工具调用能力。你可以将本地 Python 函数或 OpenAPI 规范注入给模型，当用户提问需要外部计算或查询实时数据时，模型会自动输出包含结构化参数的函数调用请求（Function Call）：

📄function_calling.py
PYTHON
python
import os
import google.generativeai as genai

# 1. 定义一个提供给模型调用的本地工具函数
def get_current_stock_price(ticker: str) -> str:
    '''获取指定美股股票代码的最新价格。'''
    # 此处模拟外部 API 查价
    prices = {'GOOGL': '$185.20', 'AAPL': '$225.40', 'MSFT': '$448.10'}
    return prices.get(ticker.upper(), '未找到该股票数据')

genai.configure(api_key=os.getenv('GEMINI_API_KEY', 'YOUR_API_KEY'))

# 2. 将函数注入工具库并启动模型
model = genai.GenerativeModel(
    model_name='gemini-1.5-pro',
    tools=[get_current_stock_price]
)

chat = model.start_chat(enable_automatic_function_calling=True)
response = chat.send_message('请问 Alphabet (GOOGL) 现在的股价是多少？')
print(response.text)

六、结构化数据输出 (Structured JSON Outputs) ​

传统的 Prompt 约束往往会出现输出夹杂非 JSON 废话的情况。Gemini API 提供了原生的 Schema 强制约束模式：

📄json_mode.py
PYTHON
python
import os
from typing import List
from pydantic import BaseModel
import google.generativeai as genai

# 定义强类型的 Pydantic 数据实体
class ProductAnalysis(BaseModel):
    product_name: str
    pros: List[str]
    cons: List[str]
    overall_score: float

genai.configure(api_key=os.getenv('GEMINI_API_KEY', 'YOUR_API_KEY'))

model = genai.GenerativeModel(
    model_name='gemini-1.5-flash',
    generation_config={
        'response_mime_type': 'application/json',
        'response_schema': ProductAnalysis,
    }
)

prompt = '请对最新款 iPhone 16 Pro 进行综合优缺点与性能评估。'
response = model.generate_content(prompt)

# 直接获得 100% 合法的 JSON 字符串
print(response.text)

七、Rate Limits 频控处理与生产级重试策略 ​

在调用 Gemini API 时，最容易遇到的报错是 429 ResourceExhausted: 429 Too Many Requests。这通常是因为免费层达到了 RPM 或 TPM 上限。

在生产环境中，必须配合指数退避（Exponential Backoff）重试库（如 tenacity）以保证服务的健壮性：

📄retry_handler.py
PYTHON
python
import os
import time
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
from google.api_core.exceptions import ResourceExhausted
import google.generativeai as genai

genai.configure(api_key=os.getenv('GEMINI_API_KEY', 'YOUR_API_KEY'))
model = genai.GenerativeModel('gemini-1.5-flash')

# 生产级指数退避：遇到 429 最多重试 5 次，重试间隔 2s -> 4s -> 8s...
@retry(
    retry=retry_if_exception_type(ResourceExhausted),
    wait=wait_exponential(multiplier=2, min=2, max=30),
    stop=stop_after_attempt(5),
    reraise=True
)
def call_gemini_safe(prompt: str):
    return model.generate_content(prompt)

try:
    res = call_gemini_safe('自动化并发测试任务')
    print('成功获得响应：', res.text)
except Exception as e:
    print('多次重试后仍然超限，执行降级逻辑：', e)

八、常见问题答疑 (FAQ) ​

Q1: 一个 Google 账号可以申请多少个 API Key？ ​

通常情况下，每个关联的 Google Cloud 项目可以创建多个不同的 API Key。你可以为不同的开发环境（如本地测试 dev、预发布 staging、生产部署 prod）分别创建独立的 Key，以便于在后台单独统计调用量与设置预算报警。

Q2: 为什么我在本地调用报错 403 User location is not supported？ ​

这表明当前脚本运行环境的外网出口 IP 属于未开放地区。在终端运行脚本前，需为命令行终端挂载代理变量，例如：

bash
export https_proxy="http://127.0.0.1:7890"
export http_proxy="http://127.0.0.1:7890"

确保代理端口通畅并走海外专线节点（详见 网络环境配置专题）。

Q3: Gemini API 免费层与付费层的主要差别是什么？ ​

免费层无需绑定信用卡，但有较严格的 RPM 频控限制，且数据可能被 Google 用于改进模型。付费层（Pay-as-you-go）不仅解除了频控上限（提升至每分钟数百甚至数千次请求），且 Google 承诺绝对不会使用用户的 API 输入与输出数据来训练任何模型，拥有完全的商业数据合规保障。

下属细分专题与长尾实战文章全景索引 ​

本专题依托 Google 官方技术白皮书与一线工程实践，下设 3 个二级细分专题 与 6 个三级专业内容集群。全量 36 篇独立实战文章 均已纳入全站知识图谱，供开发者按具体搜索意图按需查阅：

1. API 基础与快速起步 (/gemini-api/api-basics/) ​

集群 1.1：API Key 申请与安全保管 ​

序号核心实战文章与解决方案规范相对路径适用工程阶段关键技术实体
13 分钟申请首个 Gemini API Key 完整图文教学/gemini-api/api-basics/api-keys/article-1.html深度实战Gemini API / API 基础与快速起步
2Google Cloud 关联项目配置与多环境密钥隔离方案/gemini-api/api-basics/api-keys/article-2.html深度实战Gemini API / API 基础与快速起步
3生产环境中 API Key 的安全存储：环境变量与 Secret Manager/gemini-api/api-basics/api-keys/article-3.html深度实战Gemini API / API 基础与快速起步
4API Key 泄露后的紧急撤销、轮换与安全排查流程/gemini-api/api-basics/api-keys/article-4.html深度实战Gemini API / API 基础与快速起步
5针对特定 IP 限制与 HTTP Referer 白名单的安全加固技巧/gemini-api/api-basics/api-keys/article-5.html深度实战Gemini API / API 基础与快速起步
6免费 API Key 与绑定结算账号 Key 的底层网关权限差异/gemini-api/api-basics/api-keys/article-6.html深度实战Gemini API / API 基础与快速起步

集群 1.2：HTTP REST 原生接口规范 ​

序号核心实战文章与解决方案规范相对路径适用工程阶段关键技术实体
1Generative Language REST API 端点结构与请求格式详解/gemini-api/api-basics/http-rest/article-1.html深度实战Gemini API / API 基础与快速起步
2使用 cURL 在终端直接调用 Gemini 1.5 Flash 范例/gemini-api/api-basics/http-rest/article-2.html深度实战Gemini API / API 基础与快速起步
3API 请求体核心参数：contents、generationConfig 与 safetySettings/gemini-api/api-basics/http-rest/article-3.html深度实战Gemini API / API 基础与快速起步
4处理二进制文件流的 InlineData 编码传输规范/gemini-api/api-basics/http-rest/article-4.html深度实战Gemini API / API 基础与快速起步
5HTTP 响应状态码大全与标准错误对象 JSON 结构解析/gemini-api/api-basics/http-rest/article-5.html深度实战Gemini API / API 基础与快速起步
6Postman 完整调试套件下载与环境变量导入指南/gemini-api/api-basics/http-rest/article-6.html深度实战Gemini API / API 基础与快速起步

2. 高级调用与功能 (/gemini-api/advanced-calls/) ​

集群 2.1：Streaming API 原理与实现 ​

序号核心实战文章与解决方案规范相对路径适用工程阶段关键技术实体
1Server-Sent Events (SSE) 协议原理与 Gemini 流式推流机制/gemini-api/advanced-calls/streaming-api/article-1.html深度实战Gemini API / 高级调用与功能
2Python 实现异步流式生成并实现平滑终端打字效果/gemini-api/advanced-calls/streaming-api/article-2.html深度实战Gemini API / 高级调用与功能
3Node.js / Express 后端转发流式数据到前端浏览器的完整代码/gemini-api/advanced-calls/streaming-api/article-3.html深度实战Gemini API / 高级调用与功能
4流式传输中的断线重连（Reconnect）与重传保障策略/gemini-api/advanced-calls/streaming-api/article-4.html深度实战Gemini API / 高级调用与功能
5流式传输过程中如何实时统计已消耗的 Token 总量/gemini-api/advanced-calls/streaming-api/article-5.html深度实战Gemini API / 高级调用与功能
6对比 WebSockets 与 HTTP/2 在大模型流式传输中的优劣势/gemini-api/advanced-calls/streaming-api/article-6.html深度实战Gemini API / 高级调用与功能

集群 2.2：Function Calling 与工具集成 ​

序号核心实战文章与解决方案规范相对路径适用工程阶段关键技术实体
1Gemini Function Calling 原理解析：模型如何决定调用工具/gemini-api/advanced-calls/function-calling/article-1.html深度实战Gemini API / 高级调用与功能
2定义 Python 工具函数并无缝接入 Gemini 1.5 实战教程/gemini-api/advanced-calls/function-calling/article-2.html深度实战Gemini API / 高级调用与功能
3OpenAPI 3.0 规范直接转为 Gemini Tools 的自动化工具/gemini-api/advanced-calls/function-calling/article-3.html深度实战Gemini API / 高级调用与功能
4多工具链式连续调用（Multi-turn Tool Calling）实战/gemini-api/advanced-calls/function-calling/article-4.html深度实战Gemini API / 高级调用与功能
5并行函数调用（Parallel Function Calling）性能加速实践/gemini-api/advanced-calls/function-calling/article-5.html深度实战Gemini API / 高级调用与功能
6防止函数调用死循环与参数注入攻击的安全校验策略/gemini-api/advanced-calls/function-calling/article-6.html深度实战Gemini API / 高级调用与功能

3. 高可用架构与容灾 (/gemini-api/reliability/) ​

集群 3.1：Rate Limits 限流与生产重试 ​

序号核心实战文章与解决方案规范相对路径适用工程阶段关键技术实体
1429 Too Many Requests 报错原因深度剖析与指标监控/gemini-api/reliability/rate-limiting/article-1.html深度实战Gemini API / 高可用架构与容灾
2使用 Tenacity 库实现生产级指数退避（Exponential Backoff）重试/gemini-api/reliability/rate-limiting/article-2.html深度实战Gemini API / 高可用架构与容灾
3令牌桶（Token Bucket）与滑动窗口算法在客户端的实现/gemini-api/reliability/rate-limiting/article-3.html深度实战Gemini API / 高可用架构与容灾
4基于 Redis 实现分布式集群对 Gemini API 的全局速率控制/gemini-api/reliability/rate-limiting/article-4.html深度实战Gemini API / 高可用架构与容灾
5免费层 15 RPM 限制下的请求排队队列架构设计/gemini-api/reliability/rate-limiting/article-5.html深度实战Gemini API / 高可用架构与容灾
6多账号/多 API Key 自动轮询代理池的合规边界与实现/gemini-api/reliability/rate-limiting/article-6.html深度实战Gemini API / 高可用架构与容灾

集群 3.2：监控告警与可观测性 ​

序号核心实战文章与解决方案规范相对路径适用工程阶段关键技术实体
1使用 Prometheus 与 Grafana 实时监控 Gemini API 请求指标/gemini-api/reliability/monitoring/article-1.html深度实战Gemini API / 高可用架构与容灾
2接入 OpenTelemetry 实现全链路跟踪（Trace）与耗时打点/gemini-api/reliability/monitoring/article-2.html深度实战Gemini API / 高可用架构与容灾
3监控 Token 消耗曲线与突发流量预警自动化配置/gemini-api/reliability/monitoring/article-3.html深度实战Gemini API / 高可用架构与容灾
4记录用户提问与回答日志的隐私合规与数据掩码方案/gemini-api/reliability/monitoring/article-4.html深度实战Gemini API / 高可用架构与容灾
5大模型接口首字延迟（TTFT）与端到端延迟的 SLA 定义/gemini-api/reliability/monitoring/article-5.html深度实战Gemini API / 高可用架构与容灾
6构建高可用双活容灾：Gemini 与备份模型自动无缝降级/gemini-api/reliability/monitoring/article-6.html深度实战Gemini API / 高可用架构与容灾
💡 下一步推荐阅读：了解如何通过自然语言零代码快速生成应用原型，请查看 AI 应用搭建 (Build 模式)；需要更精细控制成本支出，请前往 免费额度与定价管理。

Last updated: