写代码调 Gemini 时,最常见的卡点不是 Key 不对,而是请求发去了一个拼错的地址,报出一堆看不懂的错。这篇把基础 URL 拆成「固定段 + 可变段」来看,讲清哪些部分该改、哪些千万别动,顺带给一套替换与自检的顺序,照着做就能把地址配对。
写代码调 Gemini 时,最常见的卡点不是 Key 不对,而是请求发去了一个拼错的地址,报出一堆看不懂的错。地址这类东西看着简单,但域名、版本段、路径段三处只要错一处,返回的报错完全不一样,排查起来很费时间。这篇把基础 URL 拆成「固定段 + 可变段」来看,讲清哪些部分该改、哪些千万别动。
先给结论:你只需要改主机名(或域名前缀)和少数的区域、项目参数,版本段和资源路径段基本是照抄的。如果你拿到的是一整串地址,正确做法是整体替换,而不是只把域名换掉、后半截继续用官方那套。中间任何一段对不上,都会直接 404 或者认证失败。
基础 URL 由哪几段拼成
把它拆成三块看:固定域名段、版本段、资源路径段,中间用斜杠连接。多数文档给的示例地址末尾不带斜杠,自己拼的时候也别多加,不少网关对末尾斜杠是敏感的,多一个字符就可能走到另一条路由上。
- 固定域名段
- 谁在提供服务,官方直连、云平台托管、中转站这一段的写法完全不同
- 版本段
- 接口协议的版本标识,不是模型版本,换模型时这一段通常不动,改了大概率直接 404
- 资源路径段
- 决定你调的是哪类能力,比如生成、嵌入、文件等,路径写错和域名写错报的错常常不一样
这三段里,只有第一段是你换服务方时要动的;第二段除非服务方明确说它换了协议版本,否则保持原样;第三段跟着你要调的能力走,和用哪家服务无关。把这三段分别存成变量,出错时一眼就能看出是哪一段的问题。
官方直连、云平台托管、中转站三种地址怎么写
| 接入方式 | 主机名来源 | 鉴权方式 | 容易踩的坑 |
|---|---|---|---|
| 官方直连 | 厂商自己的域名 | 厂商签发的 Key | Key 和服务方混用直接认证失败 |
| 云平台托管 | 云厂商的域名 | 云账号体系 | 路径里常多一层项目或区域标识,漏掉就连不上 |
| 中转站 | 中转站自己的域名 | 中转站发的 Key | 文档给的是一整串,只换域名不换后半截会 404 |
- 官方直连的地址和 Key 必须是同一家,从别处借来的 Key 填进去只会得到认证错误,不会提示你「服务方不匹配」;
- 云平台托管多出来的那层项目或区域标识,位置在路径中间,不是查询参数,删掉就直接路由不到;
- 中转站会把完整的接入地址连同 Key 一起给你,把这串整体替换掉原来的官方地址,别只替换域名那一段;
- 三家对照着看的时候,先确认版本段写法是否一致,不一致说明协议对不上,不能硬套。
如果你不确定手里这家中转站当前能不能稳定用,可以先到站内的中转站可信度检测页面看它最近的可用性和响应情况,再决定要不要接。地址对不对是一回事,服务本身稳不稳是另一回事。
区域与项目号在地址里的位置
区域标识一般出现在主机名或路径中间,选错区域的表现很有迷惑性:连接是通的,但返回「资源不存在」。很多人第一反应是模型名写错,其实是区域选错了。这种错和地址拼错的报错长得不一样,能靠这个快速区分。
项目号这类参数在不同接入方式里出现的位置不一样,有的在路径里,有的在请求头里。先看清文档再填,别凭感觉往 URL 后面接。接错位置的后果是请求被拒,而且日志里未必写得清楚。
- 抽成配置项把区域和项目号从代码里抽出来,放进配置文件或环境变量,别硬编码进业务逻辑
- 按环境分别配值开发和生产用不同的配置块,同一份代码换配置就能切区域,避免复制粘贴改漏
- 启动时打印一次服务启动时把最终拼出来的基础地址打一条日志,出问题时第一时间能核对,比翻代码快
替换与自检的执行顺序
换地址的时候别一上来就把整套业务跑起来,那样出错你根本分不清是地址、鉴权还是参数的问题。下面这个顺序是从小到大的,每一步都能单独验证。
- 先打最简请求用最短的一行请求验证域名和版本段,不接业务代码,确认通了你再往下走
- 分段替换域名、版本段、路径段各存一个变量,逐个换,哪一段错了一眼能看出来
- 地址和 Key 一起换如果切到中转站,地址和 Key 要同时换再测;分开换很容易把 Key 的问题误判成地址问题
- 对不上时看文档原文服务方文档给的是完整串就整体复制,别自己拆开重组,重组顺序错了很难查
还有一个容易被忽略的点:如果你是在本地调试通过、上线就失败,先看生产环境的环境变量有没有把基础地址覆盖掉。配置文件层层覆盖导致的地址错位,比手动拼错更难查。
这些做法什么时候不适用
上面讲的路径结构,前提是服务方按常规方式暴露接口。以下几种情况要换个思路,硬套本文的拆法反而会误导你。
- 云平台托管和自建网关的路由规则自成一套,本文的路径结构只能做参考,必须以各自文档为准;
- 服务方做了路径重写或前置反代时,你看到的表面地址和实际转发地址可能不同,要按服务方给出的入口为准;
- 批量迁移多个服务时,逐个手改地址不如把地址集中到一份配置里统一管理,改一处生效一片;
- 如果是内部私有部署,地址由运维统一下发,不要去猜域名规律,直接要一份接入清单更省事。
想对比各家当前的基础地址写法、区域支持和接入注意事项,可以到站内的 API 资料库看整理好的对照,那里的地址和参数写法会随服务方更新而调整,以页面上的内容为准。
下一步地址配对只是接入的第一步,想知道当前这家服务方的价格和稳定性值不值得长期用,去站内价格追踪页面核对当时的数字,再决定要不要把它写进正式环境。→常见问题
基础 URL 里到底哪个部分会随模型变化?
多数接入方式里,模型名是单独放在请求体里的字段,不写进 URL。URL 里变的主要是版本段和资源路径。所以换模型一般不用改地址,改地址往往是因为换了接入渠道或区域。真拿不准就去翻对应厂商的官方页面核对当前口径。
地址写对了还是报错,先查什么?
按顺序来:先确认 Key 是不是这家签发的,再确认版本段是不是这家在用的写法,最后看区域或项目参数有没有漏。三者都对还报错,再去查请求体和模型名。状态码类的问题可以对照报错速查那篇,按错误文本判断的那种情况另看一篇。
换中转站时,地址要整段替换还是只换域名?
建议整段替换。很多中转站虽然保留了相近的路径结构,但版本段或前缀可能不同,只换域名容易出现「能连上但不认识这个路径」的情况。替换后先用最小请求测通,再上业务代码。选站之前可以先看看站内的中转站目录和实测页做个比对。