想在国内把 Gemini 接进自己的项目，大部分人会先撞上三堵墙：AI Studio 的 Key 申请要海外网络、免费额度掐得死、付费绑卡绑不上。这篇把从拿 Key 到跑通代码的完整链路写清楚，价格表用的是小鱼API 当前实际计费，可以直接对着算成本。
选型上最常见的错误是以为越贵越好。Gemini 这几档的差别不在"能不能答对"，而在"要多想几步才能答对"。想清楚这一点，钱就省下来了。
2.5 Pro 是那种"不知道选哪个就选它"的型号。文本理解、长文档摘要、常规代码补全都能胜任，上下文窗口大，中文表达也稳，不太会出现中英夹杂的怪句子。价格 0.031 元一次，适合放进批处理脚本里大量跑。几百条商品标题改写、评论归类、格式转换，跑完成本也就几块钱。
实操上有个判断方法：拿十条自己的真实任务，先用更划算的跑一遍，只有答得不好的那几条再换贵的重跑。多数团队做完这个测试都会发现，真正需要旗舰档的任务不到两成，剩下的钱原本是白花的。
3 Pro 在多步推理、数学推导、复杂表格抽取上比 2.5 好一截。0.05 元一次，和 2.5 Pro 只差不到两分钱。只要任务带一点"想清楚再说"的成分——先从合同里找条件、再判断条件是否成立、最后给结论——直接上 3 Pro 更划算，省下的返工时间远超那两分钱。
3.1 Pro 是目前 Gemini 线上最强的一档，0.09 元一次。适合代码库级别的重构分析、超长合同比对、需要反复自我修正的 agent 任务。日常聊天和写文案用它纯属浪费，一次调用的钱够 2.5 Pro 跑三回。
NanoBanana-Pro 负责文生图、图生图、局部重绘，0.27 元一次。它和文本模型不是一个赛道，做电商主图、素材批量生成时才用得上。一次调用约等于九次 2.5 Pro，所以别在调提示词的时候乱烧，先把提示词在便宜模型上打磨好再出图。
控制台本身在国内打不开，需要稳定的海外出口。另外账号注册地区如果在中国大陆，部分模型会直接不在列表里显示，调接口返回模型不支持。有人反馈同一份代码换个账号就能跑，问题通常就出在这里。
免费档对 2.5 Pro 这类型号有每分钟请求数和每日请求数双重限制，跑批量任务几分钟就耗完，然后开始成片报 429。更麻烦的是免费档的输入数据可能被用于改进模型，商业项目里贴客户资料进去基本不能这么用。
绑卡环节需要 Visa/Master 且账单地址在支持地区，国内双币卡经常被拒。这是绝大多数人放弃官方直连的直接原因——不是不会写代码，是卡在付款那一步。
更现实的问题是，就算绑卡成功，账单页的用量统计对国内开发者也不友好，出账异常时排查链路会拉得很长。
自己买海外服务器做转发。优点是链路自己可控，长期成本也不高；缺点是维护麻烦，出口 IP 一旦被风控，整条链路全挂，得换机器重来。
企业向方案，合规性和权限体系都完整，但开通流程比 AI Studio 复杂得多，还要处理服务账号鉴权。个人开发者和小团队没必要为了跑个模型去研究 GCP 项目配置。
小鱼API 这类中转站把模型统一成 OpenAI 兼容协议，接入地址是 https://xyuapi.top/v1，一个 Key 就能调 Gemini、Claude、GPT 全系列。国内直连不降智不限速，支付走支付宝微信，最低 7 元起充，试错成本很低。对只想把功能跑通的人来说，这条路省掉了"网络"和"支付"两道资格题。
它换来的还有灵活性：今天用 Gemini，明天想试 Claude，只改一个模型名就行，不用重新注册账号、重新绑卡。
| 模型 | 能力方向 | 价格（元/次） |
|---|---|---|
| gemini-2.5-pro | 通用文本、长文档 | 0.031 |
| gemini-3-pro-preview | 复杂推理 | 0.05 |
| gemini-3.1-pro-preview | 旗舰推理 | 0.09 |
| NanoBanana-Pro | 图片生成与编辑 | 0.27 |
按次计费的规则很直白：一次对话请求算一次，你发 1 个字和发 20 万字同价。写长提示词做资料分析时，这个模式比按 token 计费便宜得多——按 token 计费的平台，20 万字输入本身就是一笔不小的开销，这里成本不变。反过来，如果你只发一句"你好"，按次就比按 token 贵，所以它更适合"每次输入都不短"的使用习惯。
还有一个容易被忽略的点：按次计费下，多轮对话和多模态输入都不额外加价。把一张图、一份 PDF、一段日志和问题一起发过去，仍然只算一次调用。写复杂提示词的时候这一点很舒服，不用因为怕超支而把上下文砍到最短，而上下文完整恰恰是输出质量的关键。
pip install openaifrom openai import OpenAI
client = OpenAI(
api_key="你的小鱼API Key",
base_url="https://xyuapi.top/v1",
)
resp = client.chat.completions.create(
model="gemini-3-pro-preview",
messages=[
{"role": "system", "content": "你是资深后端工程师，回答直接给结论和代码。"},
{"role": "user", "content": "把这条 SQL 改成能走索引的写法：SELECT * FROM orders WHERE DATE(created_at)='2026-01-01'"},
],
)
print(resp.choices[0].message.content)接口地址必须带 /v1，只写域名会直接 404。Key 建议从环境变量读，别硬编码进仓库。
stream = client.chat.completions.create(
model="gemini-2.5-pro",
messages=[{"role": "user", "content": "用 200 字解释向量数据库里的 HNSW 索引"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)流式不只是让界面"看起来快"。长回答一次性返回很容易撞到网关的超时上限，流式边生成边吐字，体感好而且更稳。做 Web 应用时把每个分片直接推给前端，用户的等待焦虑会低很多。
npm install openaiimport OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.XYU_API_KEY,
baseURL: "https://xyuapi.top/v1",
});
const res = await client.chat.completions.create({
model: "gemini-3-pro-preview",
messages: [{ role: "user", content: "给一个 Express 全局错误处理中间件" }],
});
console.log(res.choices[0].message.content);const stream = await client.chat.completions.create({
model: "gemini-3.1-pro-preview",
messages: [{ role: "user", content: "分析这段日志里的异常模式" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}Node 这边有个坑：遍历流时分片可能不带内容（比如最后一个分片只有结束标记），取字段一定要用可选链，否则进程直接崩。
import base64
with open("chart.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
resp = client.chat.completions.create(
model="gemini-3-pro-preview",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "把这张图表里的数据整理成 markdown 表格"},
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
],
}],
)
print(resp.choices[0].message.content)图片走 base64 内联，单张控制在 2MB 以内比较稳，更大的图先压缩再传，否则容易在网关层被拦。
批量处理图片建议做成队列串行跑，别开几十个并发同时上传 base64。网关对单个请求体积有限制，并发太高反而大量失败重试，最后比串行还慢。
视频建议先抽帧成几张关键图再传，一次性丢原视频既慢又容易被截断。PDF、Word 这类文档转成纯文本塞进提示词更稳，表格用 markdown 还原。Gemini 对超长文本的容忍度很高，配上按次计费几乎没有成本压力——一份三百页的文档可以整份丢进去让它一次读完再回答，比切片再拼接的结果连贯得多。
Gemini 的报错信息大多直白，把状态码和返回文本放一起看，基本能定位到具体环节。下面这几类在实际接入时出现频率最高。
并发或速率超限。中转线路一般比官方宽松，但脚本并发开到几十路照样会被限。加退避重试：捕获异常后按 1 秒、2 秒、4 秒递增等待，超过三次再放弃。别用固定间隔死重试，那样只会把限流窗口越拉越长。经验值是单 Key 每秒别超过三到五个请求，超了就等重试。批处理最好把失败任务单独落一个队列稍后重跑，别让整批任务因为几条失败全部重来。
官方接口常见于 Key 没开通该模型、项目没启用结算、或者请求地区不在支持列表。换成中转地址能一次性绕开这三类问题。
报错里带 "not supported in your region" 或者模型名找不到，基本就是地区限制。中转站已经把这步处理掉了，模型名直接填官方名字即可，不用加前缀。
长文本任务把超时调到 120 秒以上，流式请求比非流式更不容易触发网关超时。空响应通常也是超时被截断的表现，先加超时再看，别急着怀疑模型。
给自己划三条线就够了：能一次问清楚的任务用更划算的，需要它自己推几步的用中间档，只有写代码改架构、做长文档交叉分析这类才上旗舰。生图单列一笔预算，它的单价是文本模型的九倍，混在一起算会看不清真实成本。
| 任务类型 | 推荐型号 | 单价（元/次） | 每天 200 次的月成本 |
|---|---|---|---|
| 批量改写、摘要、分类 | gemini-2.5-pro | 0.031 | 约 186 元 |
| 多步推理、结构化抽取 | gemini-3-pro-preview | 0.05 | 约 300 元 |
| 代码库分析、长链路 Agent | gemini-3.1-pro-preview | 0.09 | 约 540 元 |
| 商品图、封面图生成 | NanoBanana-Pro | 0.27 | 约 1620 元 |
月成本按 30 天估算。这张表的作用是让你在需求评审时能直接报出数字，而不是被问到成本时只能说一句「大概不贵」。生图那一行最容易被低估，做内容排期之前先算一遍它占多少预算。
客户端方面，Chatbox、Cherry Studio、酒馆、Tavo 都支持自定义 OpenAI 兼容地址，把接口地址填 https://xyuapi.top/v1、Key 填进去就能用，一行代码都不用写。VSCode 里用 Cline / RooCode / KiloCode 也一样，模型填 gemini-3-pro-preview，写代码体验比默认模型好一截。建议先用最低 7 元充一档把链路跑通，确认返回质量符合预期，再决定要不要上无限卡。