Gemini API 国内使用指南（2026）：价格、免费额度、API Key 申请、调用地址与中转

下面的价格、免费额度、开通付费的规则都取自谷歌官方文档（2026 年 10 月 17 日）；调用地址和代码在本机用测试密钥逐个跑过，报错原文来自真实返回。

调用地址速查

用第三方服务时，把上面的域名换成服务商的地址。以 api.foo 为例，原生接口是 https://api.foo，OpenAI 兼容接口是 https://api.foo/v1，写法见下文。

价格（2026 年 10 月）

谷歌把 Gemini API 分成免费档和付费档。下面是付费档的标准价格，单位是美元 / 每百万 token；「免费档」一列表示这个模型能不能免费用。

几个容易忽略的地方：

• 思考 token 按输出计费。Gemini 的新模型默认会先「想」再答，价格表里的输出价格已注明包含思考部分。
• 两次涨价已经定了：Gemini 4 Argon 从 2026 年 12 月 1 日起输入、输出都翻倍；3.8 Flash 和 3.6 Flash 从 2027 年 1 月 1 日起翻倍。按现在的价格做预算，要把这一点算进去。
• Batch 批量接口打五折，适合不急着要结果的任务。
• 谷歌搜索增强（Grounding with Google Search）：Gemini 3 及以后的模型每月合计 5,000 次免费，之后每 1,000 次 14 美元。
• 价格页上还出现了一个 Contributor 档，价格大约是标准价的一半，但它是邀请制的私测，而且数据会被用于改进谷歌产品，普通账号选不了。

生图模型（Nano Banana）按张算

谷歌按输出 token 计价，表里是官方换算的每张价格。三个生图模型都没有免费档。新出的 Nano Banana 2.1 比 Nano Banana 2 还便宜一半左右。

免费额度：哪些能免费用、限多少

• 能免费用的：3.8 Flash、3.6 Flash、3.5 Flash-Lite、3.1 Flash-Lite、3 Flash Preview，2.5 系列（限以前用过的账号），以及部分语音模型。
• 不能免费用的：4 Argon、3.1 Pro Preview、所有 Nano Banana 生图模型。
• 限额按项目算，不是按密钥算：同一个 Google Cloud 项目下建再多密钥，也共用一份额度。限额分每分钟请求数、每分钟 token 数、每天请求数，每天的额度在太平洋时间午夜重置（北京时间下午 3 点或 4 点，看美国是否在夏令时）。
• 具体数字以 AI Studio 为准：官方文档不再列固定数字，登录 AI Studio 的 Rate limit 页面能看到你这个项目每个模型的上限和用量。
• 免费档的内容会被用于改进谷歌产品；付费档不会。处理公司代码、客户数据的，别用免费档。

超出限额会返回 429 RESOURCE_EXHAUSTED，等一会儿或者第二天再试。

怎么申请 API Key

1. 用谷歌账号登录 Google AI Studio，同意服务条款。
2. 新用户会自动得到一个默认项目和一把 API Key；也可以在左侧 Dashboard → API Keys 里点「Create API key」再建一把。
3. 已经有 Google Cloud 账号的，AI Studio 不会自动建项目，要先在 Dashboard → Projects → Import projects 导入已有项目，再在里面建密钥。
4. 把密钥设成环境变量 GEMINI_API_KEY，官方 SDK 会自动读取。

两条 2026 年的新规则：

• 2026 年 5 月 28 日起，AI Studio 新建的密钥都是「授权密钥」（auth key），绑定一个服务账号，默认只能调用 Gemini API。
• 没有加任何限制的普通 API Key 会被拒绝。在 Google Cloud 控制台里自己建的老式密钥，要加上 API 限制（只允许 Generative Language API）才能继续用，否则就用 AI Studio 新建一把。

点「Create API key」是灰的、提示没有权限，说明你在公司组织的项目里缺少权限。官方的建议是找管理员授权，或者新建一个不属于任何组织的项目。

怎么开通付费

用 4 Argon、3.1 Pro、生图模型，或者需要更高限额，就要开通付费：

1. 在 AI Studio 的 Projects 页面，找到要升级的项目，点 Set up billing。
2. 填联系信息和付款方式，绑定一个 Google Cloud 结算账户。
3. 新账号要预付至少 5 美元（谷歌叫 Prepay），之后按用量从余额里扣。可以打开自动充值。
4. 余额扣到 0，这个账户下所有密钥的请求都会失败，返回 402 Payment Required，充值后恢复。

付费后按累计消费自动升级档位，档位越高，限额和每月消费上限越高：

国内能不能用

先说事实：

• 谷歌官方的可用地区列表里没有中国大陆、香港和澳门（台湾、新加坡在列）。不在支持地区时，AI Studio 会提示「Google AI Studio is not available in your region」，API 请求也会被拒绝。
• 付费要绑定 Google Cloud 结算账户和付款方式，对国内个人开发者门槛不低。

所以国内开发者常见的做法是：通过提供 Gemini 模型的第三方 API 服务调用（也常被叫作「中转」）。对代码来说只是换一个地址和密钥，调用格式不变。选这类服务要注意：

• 支不支持原生接口。只提供 OpenAI 兼容接口的，Gemini CLI 和谷歌官方 SDK 用不了，只能用 OpenAI SDK 调。
• 价格写不写清楚、能不能逐条查到调用记录和扣费。
• 数据会经过服务商。涉及敏感数据、或者用于对外提供服务的，先确认服务商的隐私条款，并遵守所在地的相关规定。

怎么挑服务商，详见 API 中转站是什么？怎么选不踩坑。

调用示例

官方：curl

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "用一句话介绍你自己"}]}]}'

官方：Python SDK

先安装：pip install google-genai。

from google import genai

client = genai.Client()  # 自动读取环境变量 GEMINI_API_KEY
resp = client.models.generate_content(model="gemini-3.8-flash", contents="用一句话介绍你自己")
print(resp.text)

官方：OpenAI SDK

已经用 OpenAI SDK 写好的程序，改两处就能调 Gemini：

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-3.8-flash",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)

通过第三方服务调用（以 api.foo 为例）

谷歌官方 SDK 用 http_options 指定地址，地址写到域名为止：

import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["APIFOO_API_KEY"],
    http_options=types.HttpOptions(base_url="https://api.foo"),
)
resp = client.models.generate_content(model="gemini-3.8-flash", contents="用一句话介绍你自己")
print(resp.text)

OpenAI SDK 的地址是 https://api.foo/v1，模型名照样写 gemini-3.8-flash。curl 的话把 generativelanguage.googleapis.com 换成 api.foo，密钥换成 api.foo 的即可，x-goog-api-key 请求头和网址里的 ?key= 两种写法都能用。

我们用一把测试密钥把这几种写法都跑了一遍（google-genai 2.31.0、openai 3.32.0），服务器日志显示请求分别到达了 /v1beta/models/gemini-3.8-flash:generateContent 和 /v1/chat/completions，说明地址和格式都对。可用的模型名和价格见 api.foo 模型广场，个别模型的名字和官方略有不同（比如生图模型），以模型广场为准。

用 Gemini CLI 的，见 Gemini CLI 安装与配置。

常见报错

报错原文可以直接复制到页面里搜索（Mac 按 Cmd+F，Windows 按 Ctrl+F）。

API key not valid（400 API_KEY_INVALID）

直接调官方原生接口、密钥不对时，返回的是 400，不是 401：

{"error": {"code": 400, "message": "API key not valid. Please pass a valid API key.", "status": "INVALID_ARGUMENT", "details": [{"reason": "API_KEY_INVALID", …}]}}

走官方 OpenAI 兼容接口时是：

[{"error": {"code": 400, "message": "Please pass a valid API key", "status": "INVALID_ARGUMENT"}}]

怎么办：重新复制密钥；在 Google Cloud 控制台自己建的密钥，检查有没有加 API 限制（没加限制的会被拒绝）。

429 RESOURCE_EXHAUSTED：超出限额

超过了每分钟、每天的次数或 token 限额，付费账号也可能是 10 分钟内的消费超过了档位上限。怎么办：等一会儿再试，代码里按 1、2、4、8 秒逐步拉长间隔重试；免费档的每日额度要等太平洋时间午夜重置。官方 Python SDK 默认会对 429 和 5xx 自动重试。

402 Payment Required：余额用完了

预付余额扣到 0，整个结算账户下的密钥都停了。怎么办：去结算账户充值，或者打开自动充值。这个错误不要重试，充值前重试也不会成功。

403 PERMISSION_DENIED：没有权限

密钥没有访问这个模型或资源的权限，比如密钥属于别的项目、限制里没勾选 Gemini API。怎么办：检查密钥属于哪个项目、有没有权限。

404：模型不存在

模型名写错了，或者模型已经下线。比如 gemini-3-pro-preview 已经停用，gemini-2.0-flash 也已关闭。怎么办：对照官方模型列表改成现有的名字。

地区不支持

在不支持的地区使用时，AI Studio 提示 Google AI Studio is not available in your region（官方文档原文）。API 请求也会被拒绝，社区里常见的报错原文是 User location is not supported for the API use.。怎么办：只能在支持的地区使用官方服务，或者改用第三方 API 服务。

用第三方服务时的报错

报错的格式由服务商决定。比如 api.foo 这类基于 New API 搭建的服务，密钥不对时返回 401 无效的令牌，余额不够时返回 用户额度不足。更多见 API 报错排查大全。

相关阅读

• Gemini CLI 安装与配置：国内安装、免费额度、接第三方 API
• API 中转站是什么？怎么选不踩坑
• 大模型 API 聚合平台是什么
• API 报错排查大全

参考资料

谷歌官方文档，2026 年 10 月 17 日查阅：价格、限额、可用地区、API Key、结算、OpenAI 兼容、模型、错误码、问题排查。