> https://router.one/zh/blog/gemini-api-china-guide 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 发布：2026-05-09 · 修订：2026-08-26 · 作者：Router One Team

# 国内使用 Gemini 3.1 Pro 与 Gemini Code Assist 完整指南

_国内开发者如何稳定使用 Gemini 3.1 Pro 的 1M 上下文与 Gemini Code Assist——免翻墙、支付宝/银行卡付费、低延迟。_

Google 的 Gemini 3.1 Pro 是市面上最强的模型之一——百万 token 上下文窗口、扎实的编码分数、很有竞争力的价格。Gemini Code Assist 这个 IDE 助手共享同一系列。国内开发者面临的麻烦和 Google 其他服务一样：`generativelanguage.googleapis.com` 在大陆网络上不稳定可达，Google Cloud 计费要的卡国内大多数发不了。

这篇文章讲清 2026 年真正能跑通的路径——API、Gemini Code Assist，以及 Gemini 的百万上下文能解锁的具体用例。

## Gemini 值得折腾的地方

进入配置之前，先说清为什么值得。Gemini 3.1 Pro 在三个对真实工程重要的维度上领先 GPT-5.5 和 Claude Opus 4.7：

- **上下文窗口。**100 万 token 意味着可以把一个中型代码库整个塞进 prompt，跨文件问架构问题。这一项本身已经不构成差异化——GPT-5.5 与 Claude Opus 4.7 同样是百万级窗口——真正该比的是在整个窗口上的检索质量，而不是标称数字。
- **成本结构。**你真正能控制的杠杆是每一轮往窗口里塞多少上下文——token 账单跟着它走，而不是跟着调用次数走，所以接近百万 token 的 prompt 是一个明确的花钱决策，而不是意外。Router One 自己对每个 Gemini 模型的挂牌单价，和目录里其他模型并排列在[模型目录](https://router.one/zh/models)。
- **多模态。**Gemini 原生在同一会话里处理视频帧、音频、PDF。处理"截图日志、带附件工单、带图文档"这类内容时直接拉满。

更全面的对比见 [2026 LLM 选型指南](https://router.one/zh/blog/llm-comparison-2026)；编码方向的具体 benchmark 见 [DeepSeek V3 vs Claude 4 vs GPT-4.1 编程能力对比（2026 年 4 月）](https://router.one/zh/blog/deepseek-v3-vs-claude-4-vs-gpt-4-1-coding)。

## 两堵网络墙

Google 的开发者端点——Gemini API 走 `generativelanguage.googleapis.com`，Vertex AI 走 `aiplatform.googleapis.com`——背后都是 Google 全球基础设施。从国内看：

- 连通性时好时坏。城市和 ISP 之间差异大，同一条链路按小时浮动。
- 就算通，延迟也是 200-500ms 加长尾，对流式输出体验摧毁性的。
- 鉴权 token（Application Default Credentials、OAuth）会周期性刷新失败，因为 OAuth 端点本身就不稳。

常见的几种自救：

1. VPN——能用，但每个请求都加延迟，而且要常开。
2. 香港/新加坡部署一个代理——单人开发可以；做成生产服务从国内调过去就不行。
3. 在国内能用的区域上的 Vertex AI——只有 Google Cloud 客户加全球计费账号才走得通。

第四条路，也就是这篇文章的重点：通过[国内可达、人民币结算的网关](https://router.one/zh/gemini-api-china)调 Gemini。

## 通过 Router One 调 Gemini

[Router One](https://router.one/zh) 把 Gemini 3.1 Pro 暴露在一个 OpenAI 兼容端点后面，DNS 解析直接落到对国内友好的基础设施上。设两个环境变量，像调任何模型一样调它：

```bash
export OPENAI_BASE_URL=https://api.router.one/v1
export OPENAI_API_KEY=sk-your-router-one-key
```

```python
from openai import OpenAI
client = OpenAI()

resp = client.chat.completions.create(
    model="google/gemini-3.1-pro-preview",
    messages=[{"role": "user", "content": "给 ClickHouse 设计一个查询优化器架构"}],
)
print(resp.choices[0].message.content)
```

需要更便宜更快可以切到 `google/gemini-3.7-flash`——最新一代 Flash，截至本次更新也是目录里单价最低的 Gemini 档；平台上其他模型不换 SDK 直接切 model 字段。计费走人民币，支付宝或银行卡充值——完整支付流程见 [国内给 OpenAI/Claude API 充值完整教程](https://router.one/zh/blog/wechat-pay-alipay-openai-claude-api)。

## 用好百万上下文

百万窗口你不喂对内容就是浪费。几个值得知道的模式：

**全代码库提问。**`find . -name "*.go" | xargs cat` 把 repo 拼进一个 prompt，问"这个单体拆成微服务的话哪里最痛？"对 ~15 万行的 Go、~10 万行的 TypeScript 都能塞下，再大就接近窗口边缘了。

**长文档分析。**把 700 页法律合同、整年的客户反馈 CSV 一次性丢进 prompt。检索 vs 上下文的取舍翻了：百万上下文下，常常可以跳过 RAG，让模型直接看全部。

**多文档推理。**架构 review 一次性给到 PRD + 设计文档 + 已有代码 + 最近事故。模型同时看到四份；能发现 RAG 流水线漏掉的不一致——因为切片之间从来没共现过。

实战注意：超长输入下流式输出会延迟开始，模型确实需要把所有内容读完。接近百万 token 的 prompt 第一个 token 打头一般 3-8 秒。

## Gemini Code Assist

Gemini Code Assist 是 Google 的 IDE 插件（VS Code、JetBrains、Android Studio）。模型和 API 一样，但默认走 Google 自管端点。国内大多数情况下，插件在 OAuth 回调步骤失败。

当下两条可行路：

1. **直接调 API + 自己包薄壳。**Router One 端点 + Continue.dev 这样的可定制插件，质量是 Gemini 的，网络是你掌控的。
2. **等插件支持自定义端点。**2026 H1，Gemini Code Assist 设置里只对 Vertex AI 用户开放自定义 endpoint。如果哪天对一般 API 用户开放，把 Router One 的 URL 填进去就完事。

目前国内团队用 Gemini 做编码，多数是 API + Continue / Cursor（自定义端点）/ Claude Code（也能指向任意 OpenAI 兼容端点——配置见 [Claude Code 配置指南](https://router.one/zh/blog/claude-code-setup-guide)）。

## 模型阵容

你要在这几代 Gemini 之间做选择，各自适合的场景如下：

| 模型 | 能力画像 | 最适合 |
| --- | --- | --- |
| Gemini 3.1 Pro | 1M 上下文、64K 最大输出、原生多模态（视频帧 / 音频 / PDF） | 长上下文分析、深度推理、全代码库 prompt |
| Gemini 3.7 Flash | 最新一代 Flash（2026-08-17 上架）——1M 上下文、64K 最大输出，支持视觉与工具调用，调用方式与 Pro 一致 | 高频任务、延迟敏感链路、最便宜的 Gemini 兜底 |
| Gemini 3.5 Flash | 更早一代 Flash，调用方式完全一致 | 已经在它上面验证过的 prompt；是否仍在售以模型目录为准 |
| Gemini 3（2026 年 1 月） | 上一代 | 已经在它上面验证过的 prompt；是否仍在售以模型目录为准 |

这里不转载各厂商的价目表——它们一直在变，一张过期的表比没有表更糟。[模型目录](https://router.one/zh/models)上列着 Router One 在售的每个 Gemini 模型的挂牌单价，旁边就是上下文窗口和能力标签，部分模型最低官方价 1 折。Router One 把按量 token 费用和结账费用分开展示：人民币充值涉及的 FX 与支付通道费用会在确认前显示，已上线订阅套餐会单独说明订阅经济模型。Gemini 3.1 Pro 在前沿质量上和 Claude Opus 4.7、GPT-5.5 有得比；真正拉开账单差距的很少是标价，而是每一轮带了多少上下文。

## 什么时候专门挑 Gemini

不是每个任务都最适合 Gemini。粗略指南：

- **挑 Gemini 3.1 Pro：**上下文大小重要时——跨文件重构、长文档 QA、多模态流水线、任何不想用 RAG 的场景。
- **挑 Claude Opus 档（当前为 Claude Opus 5）：**生产级 Agent 循环最强——Claude Code、多工具 Agent、长程规划。见 [DeepSeek V3 vs Claude 4 vs GPT-4.1 编程能力对比（2026 年 4 月）](https://router.one/zh/blog/deepseek-v3-vs-claude-4-vs-gpt-4-1-coding)。
- **挑 GPT-5.5：**短而严谨的 prompt 下需要精确指令执行，延迟比深度更重要时。
- **挑 Gemini 3.7 Flash：**高量、成本敏感的任务——吞吐和更便宜的 token 账单比最后几个点的质量更重要时。

## 常见问题

**Vertex AI 的 context caching 之类的特性怎么办？**
prompt 缓存是底层模型 API 的能力：某个调用能不能吃到缓存、缓存 token 怎么计费，取决于模型本身和请求的构造方式——以模型目录和你自己的请求 trace 为准，不要想当然。Vertex 专属扩展（自部署模型端点、batch prediction）目前没有通过 OpenAI 兼容接口暴露。如果你专门需要 Vertex，请在 Google Cloud 项目下用接受你信用卡的计费账号跑 Vertex，其他模型用 Router One。

**能在 Router One 上用 Gemini 原生 SDK（`google-generativeai`）吗？**
当下最干净是 OpenAI 兼容接口。原生 Google SDK 用的是 Google 专属鉴权，转发不过来。多数团队要么用 OpenAI SDK 配 model="google/gemini-3.1-pro-preview"，要么自己写一层薄包装直接打 Router One 的 chat-completions 端点。

**embedding 怎么办？**
目前 Router One 目录里没有 embedding 模型，也没有 `/v1/embeddings` 端点。OpenAI 兼容接口覆盖 chat completions、Anthropic 风格 messages、Responses API，以及图像/视频生成。以 [router.one/models](https://router.one/zh/models) 为准；如果现在就需要 Gemini embedding，请直连调用并把这部分代码单独封装，方便日后切换。

**支持 Gemini 的图像生成模型吗？**
图像生成（Imagen 3）是 Vertex AI 的一部分，独立计费独立服务。本文聚焦 Router One 上的文本模型路由；最新覆盖见 [router.one/models](https://router.one/zh/models)。

**有免费额度吗？**
Google 给 Gemini API 直连提供少量免费额度，但有上面说的网络问题。Router One 没有免费层，默认可按量从钱包扣费；如果想要可预测的月度成本，已上线订阅套餐可用。

**以后想切到 Google Cloud 直连，代码怎么保持兼容？**
用 OpenAI SDK + `OPENAI_BASE_URL` 写。哪天切到 Vertex/Gemini API 直连，改 base URL，可能还要改 SDK 调用形态。把 prompt 和工具放在独立模块里，迁移就是机械的事。

## 结论

Gemini 3.1 Pro 的百万上下文、多模态、激进定价让它在很多任务上是对的选择——尤其是输入量大的场景。国内直连不稳；通过 Router One 它就和任何 OpenAI 兼容端点一样工作，支付宝人民币计费。

更宏观的跨厂商路由叙事见 [AI 模型路由详解](https://router.one/zh/blog/ai-model-routing-explained)；端到端如何在生产环境跑多模型 Agent，见 [生产环境 AI Agent 完整指南](https://router.one/zh/blog/ai-agents-production-guide)。

## 相关页面

- 本页规范地址：https://router.one/zh/blog/gemini-api-china-guide
- LLM API 支付：https://router.one/zh/wechat-pay-llm-api
- 全部博客文章：https://router.one/zh/blog
- 模型与每模型 token 价格：https://router.one/zh/models（markdown：https://router.one/zh/models.md）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md