Gemini API 国内怎么调?3 Flash / 3.6 Flash / 3.1 Pro 价格与选型(2026)
Gemini API key 怎么获取、官方 OpenAI 兼容地址支持哪些端点、国内调用前要先核的地区与付款规则;附 Gemini 3 Flash / 3.6 Flash / 3.1 Pro 的官方价格(2026-11-03 查阅)和在 cocodot 调用的代号 mgg-7 / mgg-12 / mgg-8。
1. 先分清常见的两条路:官方 Gemini API 和 OpenAI 兼容中转
两条路的区别在于你和谁结算、用谁发的 key。官方路径里,你在 Google AI Studio 拿 Gemini API key,key 挂在一个 Google Cloud 项目下,项目决定结算账号、配额和权限;请求发到 generativelanguage.googleapis.com,可以用 Google 自己的 GenAI SDK,也可以用官方 OpenAI 兼容地址接 OpenAI SDK。这条路至少要过三关:你所在的地区在官方可用名单里、调付费型号时项目开通了结算、Google 结算接受你的付款方式。中转路径里,你拿的是中转服务商发的 key,请求发到服务商的地址,由服务商对接上游,你只和服务商结算;代码层面通常只改 base_url、api_key、model 三处。两条路各有取舍:官方路径能用到 cocodot 中转没有上架的型号(比如 Gemini 4 Argon、Gemini 3.8 Flash)、官方的 extra_body 扩展字段和免费档;中转路径能用哪些型号以服务商的在售列表为准,扩展字段是否透传要看服务商文档。本文先讲官方怎么拿 key、兼容地址怎么填、思考档位怎么设,再讲地区和付款怎么自查,最后讲选型和在 cocodot 调用。官方直连和中转各适合什么情况,详见 /hub/llm-api-vs-official-when。
2. Gemini API key 怎么获取:官方步骤和 2026 年的两条新规则
按 AI Studio 的 API key 文档(aistudio.google.com/docs/api-key,2026-11-03 查阅,以官方页为准):① 打开 AI Studio 的 API Keys 页面,点 Create API key。② 新用户接受服务条款后,AI Studio 会自动建一个默认的 Google Cloud 项目和一把 key;已经有 Google Cloud 账号的用户不会自动得到默认项目,要先在左侧 Dashboard 的 Projects 视图里点 Import projects 把已有项目导入,再回 API Keys 页建 key。③ 把 key 放进环境变量 GEMINI_API_KEY 或 GOOGLE_API_KEY,官方客户端库会自动读取;两个都设了时 GOOGLE_API_KEY 优先,机器上同时留着旧 key 和新 key 时,先确认程序读到的是哪一把。2026 年有两条容易踩的新规则。第一,key 分两种:标准 key 只把请求关联到项目做结算和配额,不标识调用者;auth key 直接绑定一个 Google Cloud 服务账号,默认只能调 Gemini API。官方写明从 2026 年 5 月 28 日起,AI Studio 里新建的 key 一律自动建成 auth key。第二,不加限制的标准 key 会被拒:官方写明 Gemini API 拒绝来自不加限制的标准 key 的请求,并且从 2026 年 5 月 7 日起会封停长期闲置、不加限制的 key,被封的 key 在 AI Studio 里带 Blocked 标签,只能新建 key 或改用加了限制的 key。给旧 key 加限制的步骤:在 API Keys 页找到标着 Unrestricted 的 key → 鼠标移到标签上点 Add restrictions → 选 Restrict to Gemini API only → 点 Restrict key 确认;操作人需要 apikeys.keys.update 权限(API Keys Admin、Editor 角色都带)。安全方面,官方要求不要把 key 提交进 Git 这类源码仓库,生产环境不要把 key 写死在网页或移动端里,前端应用应由你自己的后端服务代发请求。key 管理的更多做法见 /hub/ai-api-key-security-guide。
# 两个都设时,官方客户端库优先用 GOOGLE_API_KEY
export GEMINI_API_KEY="你的 Gemini API key"
unset GOOGLE_API_KEY
# 确认当前 shell 里只剩一个
env | grep -E '^(GEMINI|GOOGLE)_API_KEY=' | cut -d= -f13. 官方 OpenAI 兼容地址:base_url 怎么填,支持什么、不支持什么
官方兼容文档在 aistudio.google.com/docs/openai(旧地址 ai.google.dev/gemini-api/docs/openai 已跳转到这里,2026-11-03 查阅)。用法是在 OpenAI SDK 里改三处:api_key 换成 Gemini API key,base_url 设成 https://generativelanguage.googleapis.com/v1beta/openai/,model 换成 Gemini 的型号 ID;REST 调用时聊天补全的完整路径是 /v1beta/openai/chat/completions,key 放在 Authorization: Bearer 请求头里。页面上给了示例的能力包括:聊天补全与流式输出、函数调用、图片理解、结构化输出(JSON)、音频输入(示例是转写)、embeddings(示例型号 gemini-embedding-2、gemini-embedding-001)、图片生成(gemini-2.5-flash-image、gemini-3-pro-image-preview)、Batch(建任务、查状态、看结果)、列出和查询模型,以及与 OpenAI 同名同逻辑的 service_tier 参数(对应 Flex 和 Priority,不传时为 standard)。不支持或要注意的地方:① 官方写明对 OpenAI 库的支持仍处于 beta,功能还在扩展;② 经兼容层上传、下载文件目前不支持,Batch 示例里的文件上传下载用的是 Google 自己的 genai 客户端;③ 视频生成型号 gemini-omni-1.1-flash 不支持兼容层的 /v1/videos 端点,Veo 3.1 Preview 系列已于 2026 年 10 月 22 日停用;④ 图片生成一节写明,没列出的参数会被兼容层静默忽略 —— 不报错不等于参数生效;⑤ 页面没有提到 Responses API、Assistants 这类接口,别默认能用,先自己测。Gemini 特有的配置(cached_content、thinking_config 等)通过 extra_body 传。官方还有一句建议:如果你原本就没在用 OpenAI 库,直接调 Gemini API 更合适。
# 官方 OpenAI 兼容地址(aistudio.google.com/docs/openai,2026-11-03 查阅)
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
# 1) 先列出这把 key 能看到的 Gemini 型号,确认型号 ID 逐字一致
print([m.id for m in client.models.list() if "gemini" in m.id])
# 2) 流式聊天补全
stream = client.chat.completions.create(
model="gemini-3.6-flash",
messages=[{"role": "user", "content": "用两句话解释什么是 embeddings"}],
stream=True,
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="")没有海外卡也能调大模型:cocodot 的 OpenAI 兼容 API,改 base_url 就能调在售型号。
支付宝 / 微信支付(人民币)、USDT / USDC 充值 · 按 token 计费 · 改 base_url 即可接入
4. 思考档位:reasoning_effort 在兼容层里怎么映射
官方定价页的输出价一栏写明含思考 token,所以思考档位直接影响账单。兼容层用 OpenAI 的 reasoning_effort 参数控制思考,官方页给了一张映射表(2026-11-03 查阅):minimal 在 Gemini 3 Flash 和 Gemini 3.1 Flash-Lite 上对应 minimal,在 Gemini 4 Argon 上按 low 处理,在 Gemini 2.5 上是 1,024 token 的思考预算;low / medium / high 在这三个型号上分别对应同名档位,在 Gemini 2.5 上分别对应 1,024 / 8,192 / 24,576 token 的预算。不传 reasoning_effort 时,用型号自己的默认档位或预算。三条容易踩的规则:① 官方写明 Gemini 2.5 Pro 和 Gemini 3 系列不能关闭思考,官方给的关闭方法是对 2.5 系列型号把 reasoning_effort 设成 none(2.5 Pro 除外);② reasoning_effort 和 extra_body 里的 thinking_level / thinking_budget 功能重叠,不能同时传,两者都写的老代码要删掉一个;③ 这张表没有单列 Gemini 3.6 Flash 和 Gemini 3.1 Pro,这两个型号各档的实际行为以官方文档后续更新为准。上线前的做法:用同一条提示分别跑 low 和 high,各跑几次,记下响应 usage 里的输出 token 数、延迟和回答是否合格,再按合格结果的平均花费定档。算预算时把思考 token 当作输出 token 计入,别只按可见正文的长度估。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
prompt = [{"role": "user", "content": "一个水池有进水管和出水管,写出求注满时间的步骤"}]
for effort in ["low", "high"]:
r = client.chat.completions.create(
model="gemini-3-flash-preview",
reasoning_effort=effort, # 别和 extra_body 里的 thinking_level / thinking_budget 同时传
messages=prompt,
)
print(effort, r.usage.completion_tokens, len(r.choices[0].message.content or ""))5. 地区限制:先查官方名单,再看报错原文
Gemini API 和 Google AI Studio 共用一份可用地区名单(aistudio.google.com/docs/available-regions)。2026-11-03 查阅时,名单里没有中国大陆。官方页写的是:如果你打开 AI Studio 时被带到这一页,你所在的地区可能不受支持;不在名单里的国家和地区,官方建议试 Gemini Enterprise Agent Platform 上的 Gemini API。页面还有一条小字:在 Colab 里使用时,地区限制看的是 Colab 实例所在的地区,不是用户本人的位置。能否使用以官方页面当前内容和官方对国家和地区的规定为准。自查顺序:① 在名单里找你本人和公司所在的国家或地区;② 看 AI Studio 的 API Keys 页能不能打开、能不能建 key;③ 建好 key 后调一次模型列表(上一节代码的第一步),保留完整的报错原文和请求时间。报错原文比状态码有用:别凭一个 403 或 400 自己下结论,把原文和请求时间交给 Google 的支持渠道核对。如果改走 Gemini Enterprise Agent Platform,它在你所在的地区能否开通、接受哪些付款方式,以该平台自己的官方条款和结算文档为准。区域类报错的排查思路见 /hub/gemini-api-403-location-fix,key 无效或被拒的通用排查见 /hub/api-401-invalid-api-key-fix。
6. 官方付款与结算:预付、HTTP 402、按层级的月上限
付费型号(比如 Gemini 3.1 Pro,它没有免费档)要先给项目开结算。按 AI Studio 结算文档(aistudio.google.com/docs/billing,2026-11-03 查阅):在 API Keys 或 Projects 页点 Set up billing(Projects 页在项目的 Billing Tier 一栏);第一次用 Google 结算要选国家、同意条款、确认联系信息并添加付款方式,以前建过 Google 结算账号的会让你从已有账号里选。新用户默认走预付,最少买 $5,预付余额最多 $5,000;额度购买 12 个月后过期,除了切换成后付,预付不退款。余额到 $0 时,这个结算账号下所有项目的所有 key 会同时停用,请求返回 HTTP 402,充值后恢复,项目不会自动降回免费档。付费层分三级,上限按结算账号算:Tier 1 是绑好有效的结算账号,每月 $250;Tier 2 要求累计付款 $100 且距首次付款满 3 天,每月 $2,000;Tier 3 要求累计 $1,000 且满 30 天,每月 $20,000 到 $100,000(页面两张表的写法略有出入,以官方页为准);累计到上限后,所有关联项目暂停到下个月 1 日,可以按页面上的表单申请提额。官方还写明 AI Studio 的计费数据最多可能延迟约 10 分钟,这段时间里用量可能超出余额或上限。预付余额不等于硬上限:余额用尽时,已经发出的请求仍可能计费,以账单为准。不要假设预算提醒会自动停止扣费;平台有没有能自动停用的消费上限、对哪些服务生效,以官方文档为准(结算页把项目级消费上限标为实验功能)。付款方式这一步,Google Cloud 的付款方式页(docs.cloud.google.com/billing/docs/how-to/payment-methods)写明,能用哪些付款方式取决于结算账号的币种和国家,预付卡不受理,需要双重验证的借记卡也不受理。用 cocodot 的卡在 Google 结算付款,我们目前没有实测记录 —— 不是说不行,而是我们不承诺没验证过的事。如果要试,先按最低额付一次、跑一个小请求,隔天对一遍账单再加量;能否付款以 Google 的审核和实际结果为准。付款被拒时,请向发卡行和商户确认拒绝原因,别在短时间内反复重试。
7. 选型:Gemini 3 Flash、3.6 Flash、3.1 Pro 怎么分工
官方定价页对这三个型号的定位(2026-11-03 查阅):Gemini 3 Flash(gemini-3-flash-preview)写的是提供基础速度和智能的旧版 Flash;Gemini 3.6 Flash(gemini-3.6-flash)是上一代 Flash,模型页标为 Stable;Gemini 3.1 Pro(gemini-3.1-pro-preview)是第三代 Pro,面向多模态理解、agent 能力和氛围编程。官方定价页把 Gemini 3.8 Flash 描述为 Google 最智能的 Flash,把 Gemini 4 Argon 称为旗舰推理模型,这两个 cocodot 的中转都没有。按官方价格结构看分工:3 Flash 在这三个型号里官方单价最低,但音频输入另按 $1.00 计,适合文本为主、量大、单次价值低的调用(打标、清洗、初筛、摘要);3.6 Flash 的官方价按日期分两段,2027 年 1 月 1 日起输入、输出都翻倍,做明年的预算要按新价算;3.1 Pro 按提示长度定档,提示超过 200K token 时输入、输出都按高档价(输入 $2 → $4,输出 $12 → $18),跑长文档、长对话前先估一下会不会过线,能拆就拆。有个容易漏的点:Gemini 3 Flash 和 3.1 Pro 的官方型号 ID 都带 -preview 后缀,官方模型页对 Preview 型号的说明是弃用前至少提前 2 周通知,定价页对 3 Flash 的描述也已经是旧版型号 —— 长期项目在官方路径上用 -preview 型号,要定期看官方模型页和弃用公告。选型别只看代数和单价:拿你自己的 20–50 条真实样本、固定一套验收标准,三个型号各跑一遍,记下合格数、每个合格结果的花费和平均延迟,再决定哪些任务放 Flash、哪些上 Pro;也可以试两层做法:先让便宜型号处理全部条目、只把它标为没把握的交给 Pro,用同一批样本对比这种做法和全量上 Pro 的合格任务成本。Flash 档和 GPT 低价档的对比见 /hub/gemini-flash-vs-gpt-luna,官方新旗舰的价格和用法见 /hub/gemini-4-argon-api。
8. 在 cocodot 调 Gemini:代号、接入代码和迁移自查
如果官方路径在你这里走不通(地区、结算、付款任何一步),可以通过 cocodot 的 OpenAI 兼容接口调 Gemini。在售的 Gemini 型号是三个:Gemini 3 Flash(mgg-7)、Gemini 3.6 Flash(mgg-12)、Gemini 3.1 Pro(mgg-8);cocodot 没有 Gemini 4 Argon 和 Gemini 3.8 Flash,请求里别填这两个型号。开通顺序:注册 → 新用户调用 API 须先完成实名认证 → 用支付宝 / 微信支付(人民币)、USDT / USDC 充值 → 控制台建 key → 调用;注册赠送的体验额度首次充值后即可使用。单价以 cocodot 价格页实时标价为准。从官方兼容地址切过来,改三处:base_url 换成 https://cocodot.co/api/ai/v1,api_key 换成 cocodot 的 key,model 换成上面的代号。迁移时逐项自查:① 先用公开接口 https://cocodot.co/api/ai/v1/models 看型号是否在列,这个接口不需要 key;② extra_body 里的 Google 扩展字段(cached_content、thinking_config 等)属于 Google 自己的兼容层,经 cocodot 调用时别默认它们会生效,先用一条请求测试并看响应;③ mgg-12 回答前会先消耗思考 token,计入输出,max_tokens 设得太小可能只剩很短的正文,先设 1000 以上再按 usage 调;④ PDF 文档输入目前不支持,图片输入先用一张小图测通再批量;⑤ 型号名对不上的报错排查见 /hub/api-model-not-found-fix。想确认中转调到的型号和宣称的一致,可以用开源工具 probe.cocodot.co 做可复现的检查,对任何服务商都适用,包括 cocodot。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COCODOT_API_KEY"],
base_url="https://cocodot.co/api/ai/v1",
)
resp = client.chat.completions.create(
model="mgg-7", # Gemini 3 Flash;Gemini 3.6 Flash 填 mgg-12,Gemini 3.1 Pro 填 mgg-8
max_tokens=1000,
messages=[{"role": "user", "content": "把这句话翻译成英文:先小批量测试,再批量调用"}],
)
print(resp.choices[0].message.content)
print(resp.usage) # 核对输入、输出 token;mgg-12 的思考 token 计入输出Gemini 型号对照(官方价来源 aistudio.google.com/docs/pricing,付费层标准档,美元 / 每百万 token,输出含思考 token;2026-11-03 查阅,以官方定价页为准)
| 型号 | 官方 model ID | 官方输入 / 输出价 | 官方免费档 | cocodot 调用名 |
|---|---|---|---|---|
| Gemini 3 Flash | gemini-3-flash-preview(官方标 Preview) | $0.50 / $3.00(音频输入 $1.00) | 有 | mgg-7 |
| Gemini 3.6 Flash | gemini-3.6-flash(官方标 Stable) | 2026-12-31 前 $0.75 / $3.75;2027-01-01 起 $1.50 / $7.50 | 有 | mgg-12 |
| Gemini 3.1 Pro | gemini-3.1-pro-preview | 提示 ≤200K:$2.00 / $12.00;提示 >200K:$4.00 / $18.00 | 无 | mgg-8 |
| Gemini 3.8 Flash | gemini-3.8-flash(官方标 New) | 2026-12-31 前 $0.75 / $3.75;2027-01-01 起 $1.50 / $7.50 | 有 | —(中转不提供) |
| Gemini 4 Argon | gemini-4-argon | 2026-11-30 前 $2.00 / $10.00;2026-12-01 起 $4.00 / $20.00(详见 /hub/gemini-4-argon-api) | 无 | —(中转不提供) |