Gemini API免费申请教程：获取API Key、首次调用与额度排查
资料核对：2026年10月10日｜适用于希望学习API接入的新手
Gemini API免费申请的基本流程是：确认Google AI Studio可用资格，建立项目和API Key，选择当前提供免费层的模型，再发一个很小的测试请求。免费额度适合学习和小型验证，不等于所有模型、所有功能都免费。
本篇带你从密钥创建走到第一条文字回复，并解释申请成功却无法调用时该检查什么。你不需要先做一个完整网站，也不要一开始提交大批文件。
本站原创流程示意图，并非Google AI Studio截图。
先分清Gemini应用、AI Studio和API
Gemini应用用于直接聊天，AI Studio用于开发与测试，API用于程序调用。应用中的付费订阅、开发项目的账单和模型免费层，需要分别查看。
申请前打开Google AI Studio，并检查官方支持地区说明。如果页面提示所在地、年龄或账户条件不满足，先按官方资格要求处理。网络能打开页面，并不等于账户符合API使用资格。
第一步：创建项目和API Key
在AI Studio中找到API密钥管理入口。选择现有项目或按提示新建项目，再创建密钥。项目可以理解为把调用、权限和用量归在一起的工作空间；新手使用一个专门的测试项目，更容易看清用量。
记录项目名称和用途，把密钥存放到自己的凭据管理工具。不要复制进公开笔记、网页代码或截图。申请流程与环境变量名称见官方密钥文档。
如果项目列表为空，检查当前Google账号、项目访问权限和页面提示。不要因为第一次看不到项目就连续创建多个账号，这只会让后续账单与权限更难排查。
第二步：确认你选的模型确实有免费层
打开Gemini API价格页面，检查所选模型的免费层栏，以及文字、图片、搜索等功能是否分别收费。记录模型ID，后面代码里的名称必须与它对应。
即使是同一模型，不同功能也可能有不同计费规则。第一次练习只发送短文本，不启用搜索、图片生成等额外工具。免费层的数据使用规则也应一起查看，测试材料使用公开或虚构内容，不上传敏感业务数据。
截至核对日期，官方快速入门以gemini-3.8-flash演示文字调用，价格页列出了该模型的免费层。你的项目能否使用、具体额度多少，以当前控制台为准。如果型号发生调整，选择价格页仍提供免费层、且项目可以使用的型号。
第三步：在终端配置密钥和模型
以下使用Python与官方google-genai库。先安装Python，在终端确认能够执行python --version，然后安装：
python -m pip install -U google-genai
Windows用户可以在PowerShell里无回显输入密钥，避免把完整密钥写进命令历史：
$geminiSecret = Read-Host '输入Gemini API Key' -AsSecureString
$env:GEMINI_API_KEY = [System.Net.NetworkCredential]::new('', $geminiSecret).Password
Remove-Variable geminiSecret
$env:GEMINI_MODEL = 'gemini-3.8-flash'
这些设置只作用于当前终端及之后启动的子进程。运行代码时使用同一个终端；新开窗口后若提示找不到变量，需要重新配置。macOS或Linux也可使用终端的环境变量功能，具体写法见官方环境变量说明。
若同时存在GOOGLE_API_KEY，官方库自动读取时有优先顺序。下方代码明确从GEMINI_API_KEY读取，减少选错密钥的可能。
第四步：完成一条最小请求
新建gemini_test.py，保存为UTF-8，写入以下代码：
import os
from google import genai
api_key = os.environ["GEMINI_API_KEY"]
model_id = os.environ["GEMINI_MODEL"]
client = genai.Client(api_key=api_key)
reply = client.interactions.create(
model=model_id,
input="请用简体中文、三句话解释什么是API。"
)
print(reply.output_text)
在同一个终端执行：
python gemini_test.py
看到可读的中文回复，说明这次请求完成。此示例按官方快速入门中的Interactions接口组织；旧教程可能使用其他方法，复制时不要把不同接口的参数混在一起。本文没有替你执行付费或远程模型请求，实际结果以你的控制台为准。
第一次成功后，先去用量页面检查所选项目、模型和请求记录，再尝试把输入改成一小段公开资料。不要马上启动循环或一次处理几百条任务。
免费额度如何看？
常见限制包括每分钟请求数、每分钟输入Token数和每日请求数。Token是模型处理文字等内容的计量单位，并不等于一个汉字。相同请求次数下，发送整本书可能比短句更快碰到限制。
官方速率限制说明指出，限制按项目应用，不是每把密钥都独立获得一份额度。给同一个项目再建一把Key，并不能解决项目额度耗尽。
做批量练习时先串行调用，把输入压缩到必要内容，保存已成功的结果；失败任务单独记录，避免整批重新跑。
申请后报错，按这个表排查
| 提示或现象 | 重点检查 | 下一步 |
|---|---|---|
找不到GEMINI_API_KEY |
是否在同一终端运行 | 配置变量，不要打印完整密钥 |
| 模型不存在或不可用 | 模型ID、账户和项目权限 | 从当前模型文档选择可用型号 |
| 429或额度耗尽 | 每分钟与每日限制、项目用量 | 降低频率，查看对应恢复条件 |
| 权限或地区错误 | 官方支持条件及项目设置 | 按错误原因处理，不能靠重试解决 |
| 请求超时 | 服务状态、DNS与终端网络 | 用一条短请求排查连接 |
更完整的错误定位方法可以看AI API报错排查指南。
如果你已经满足服务使用条件，却确认本地连接经常中断，可以参考本站机场推荐与网络服务选购指南比较试用和客户端支持。先验证终端中的请求稳定性，再考虑购买；网络套餐不能扩大免费额度。
常见问题
Gemini API免费额度会一直不变吗？
不会作这样的保证。模型、项目资格和免费层限制可能调整，保存控制台与价格页入口，比记住一张旧额度表更实用。
有API Key就一定能免费调用吗？
不一定。还要看模型、功能、项目计费状态和额度。密钥是身份凭据，不能替代计费条件检查。
能把Key填进第三方聊天工具吗？
先确认工具可信、密钥保存方式和请求发往哪个地址。不要把官方密钥交给不明中转服务；公开发布的前端页面也不应包含密钥。
免费额度不够，还有什么选择？
学习和小型测试可以比较Gemini、OpenRouter与Ollama三条路线。如果任务要求稳定响应，需把限额、数据处理和运维成本一起纳入预算。
评论