gemini api 基础 url

入门与上手

讲清 Gemini 接口基础 URL 该填什么、官网地址和兼容地址怎么区分、填错会出什么错,给一份可照做的配置与排查清单。

很多人第一次接 Gemini,Key 拿到了、模型名也选好了,结果卡在最不起眼的一格:基础 URL。填官方地址还是兼容地址,带不带版本号,中转站给的地址能不能直接覆盖,报错又指向哪一格,全靠猜。这篇只讲这一个字段:它是什么、有几种形态、按什么顺序核对,以及什么情况下你根本不用改它。

第一次接 Gemini,多数人卡的不是 Key,也不是模型名,而是配置里最不起眼的那一格:基础 URL。填官方地址还是兼容地址,末尾带不带版本段,中转站给的地址能不能直接覆盖上去,全靠试。这篇文章只聊这一个字段——它是什么、有哪几种形态、按什么顺序核对,以及什么情况下你压根不用动它。

思路先立住:地址跟着 Key 走,不跟着模型名走。你手上这把 Key 是从哪儿拿的,基础 URL 就填那一家的。想确认当前各家官方口径和可选形态,可以到 /official-api/providers/google 对照着看,别凭记忆抄别人博客里的旧地址。

基础 URL 到底是什么,和完整请求地址差在哪

基础 URL 只是一个前缀,真正发出去的地址是「基础 URL + 路径」。SDK 会自己帮你拼后半段,所以你在这一格里多写一个斜杠、少写一段版本号,拼出来就是另一个地址。很多人以为改了基础 URL 就等于换了模型,其实只是换了台服务器在应答,模型名和 Key 归属是另外两件事。

  • 一个字段决定三件事:请求发去哪台服务器、走哪套协议格式、SDK 怎么拼后面的路径
  • 同一个 Key 换基础 URL,等于换了一台应答服务器,请求体和返回结构都可能跟着变
  • 基础 URL 不决定你能用哪些模型、扣谁的钱,那分别由模型名和 Key 归属决定
  • 不确定填哪种时,先问自己「Key 是从哪拿的」,地址跟着 Key 来源走,而不是跟着你想用的模型走

一个能立刻验证的小动作

把三样东西抄在同一行:Key 的来源页面、代码里写的基础 URL、实际请求打出去的完整路径。这三者能对上,基本就没问题;对不上,先别怀疑网络,先怀疑这一格。打开 SDK 的详细日志把真实请求地址打印出来,是最快的一步。

三种常见形态:官方原生、兼容层、中转站地址

形态路径习惯最容易踩的坑
官方原生一般带版本段,结构与兼容层不同拿兼容层的请求体去发,往往路径类报错或参数被静默忽略
兼容层为了让 OpenAI 风格代码不改逻辑就能跑,路径习惯以版本号收尾换了这种形态,模型名的写法常常也要跟着改,只改地址会白忙
中转站 / 代理把上面两种包一层,地址由服务方给Key 和地址必须来自同一家,混着用会出现地址通了却一直鉴权失败

判断方法很笨但很有效:把你手上 Key 的来源页面、代码里的基础 URL、请求路径三者抄在一行对比。中转站给的地址不要用官方地址去套,官方 SDK 也不要硬塞中转站地址。想看看当前有哪些站点可选、各自标称的协议形态,到 /sites 里对着看,别只信对方单独发你的一段地址。

落地配置清单:按这个顺序填,少走回头路

  1. 地址进环境变量,别硬编码把基础 URL 和 Key 分开存成两个环境变量,换环境时不动源码。官方 SDK 的默认值其实就带正确地址,能不改就不改。
  2. 先用最小请求验连通只发一句话,不挂工具、不接流式、不加重试,把格式和网络这两个变量先排除掉。能返回再往下走。
  3. 打开详细日志看真实地址把 SDK 实际打出去的完整 URL 打印出来,对照你写的那串字符。多数「填了但没生效」是末尾斜杠或少了版本段。
  4. 最后才加超时与重试连通性没确认之前别堆重试策略,否则真正的报错会被重试成功的那次掩盖掉,排查更难。
  5. 中转站按对方给的地址填走目录里的服务,地址以那家给的为准,不要拿官方地址去套,反之亦然。

如果同时要接多家、做多模型对比,就把地址做成可切换的配置项,而不是钉死一个。这类场景下不要图省事把官方地址和代理地址混着写在同一份配置里,后面换人维护会非常痛苦。

什么时候别动这个字段

官方 SDK 默认就带正确地址,能不动就不动。改它只能在少数场景里省点事,但一旦出问题,你的排查面就从一层变成两层——既要查网络,又要查地址对不对。多人共用一个仓库时尤其忌讳地址散在每个人本地,否则很容易出现「你这边好、我这边报错」的扯皮。

  • 延迟高,先怀疑网络出口和区域,而不是先换基础 URL;换地址往往只是换了个同样远的中转
  • 想量一条基线,去 /tools/speed-test 测,比凭感觉换地址靠谱
  • 多人协作时,地址写进统一配置,不要各改各的本地文件
  • 不适用的情况:做多模型对比、需要同时走多家通道时,就该把地址做成可切换项,而不是钉死一个

一个反直觉的判断

如果同一条代码昨天能通、今天不通,而你今天只改了模型名,那问题多半不在基础 URL。字段本身很少无缘无故失效,先看是不是服务方调整了地址或协议形态,去 /price-watch 一类的追踪页看看有没有相关变动记录。

填错之后怎么排查:按报错文本定位

报错特征先查什么再查什么
路径类(找不到接口)基础 URL 末尾斜杠版本段、SDK 是否又拼了一次路径
鉴权类Key 与地址是否同源Key 里有没有多余空格或换行
连不通 / 超时域名能不能解析端口能不能通,再回头怀疑字段

排查的原则是一次只改一个变量。看到报错先把英文代码查清楚是什么意思,拿不准就丢进 /ai-dict 对照基础概念,别凭感觉连改三个地方——那样就算好了你也不知道是哪个改对了。改完记一笔,下次同类问题能省一半时间。

基础 URL 决定请求发去哪,不决定你能用什么;地址跟着 Key 走,不跟着模型名走。
下一步想确认自己填的地址属于哪种形态、或对比不同站点的协议口径,到 /sites 对着看一遍;要是怀疑是速度问题而不是地址问题,先去 /tools/speed-test 测一条基线再说。

常见问题

gemini api base url 到底应该填官方地址还是填兼容地址?

看你手上的代码是按哪套格式写的。用官方 SDK 就按官方的来,用 OpenAI 风格的老代码就走兼容形态,两边请求体不通用。判断标准很简单:Key 从哪拿的、示例代码按哪套写,地址就跟着哪套走,不要交叉混用。具体地址字符串以来源页面为准,站内 /official-api/providers/google 有官方入口。

我把基础 URL 换成了另一家给的地址,为什么 Key 还能用但结果不对?

地址决定请求发给谁,Key 决定服务器认不认你。换地址后 Key 还能通过,说明两家在鉴权层是打通的,但模型名、参数名、返回结构未必一致,于是表现为「能返回但内容怪」。先对齐模型名写法,再对比返回字段,别直接把返回值透传给上游业务代码。

本地跑得好好的,部署到服务器就连不上,是地址写错了吗?

多数时候不是字段本身错,而是环境差异:环境变量没带过去、容器里 DNS 不通、出网策略被拦。排查顺序是先看环境变量有没有读到,再在服务器上单独测域名解析和连通性,最后才回头改地址。地址只在两边真的填了不同值时才成为嫌疑对象。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。