API 接入报 404：Base URL 到底该不该带 /v1？

地址填了，密钥粘了，模型也选了。点一下测试：404。咋的，门牌都照着抄，还能走错门？

先别跟密钥较劲。404 先看实际请求路径；Base URL 该不该带 /v1，取决于客户端自己会拼上哪段路径。 Base URL 就是交给客户端的接口基础地址，同一个网关，在不同工具里填法可以不同。

以本文引用的网关文档为例，两处配置分别是：

Codex CLI 的 OpenAI 兼容配置：https://newapi.xingqiaoapi.cn/v1
Claude Code 的 ANTHROPIC_BASE_URL：https://newapi.xingqiaoapi.cn

照搬一个地址到所有客户端，容易把门牌号又抄了一遍。注意，这只是这两种配置的填法，不能推出“所有 OpenAI 客户端都带 /v1”。

先把三段地址拆开

一次请求需要网关域名与接口路径，模型 ID 则通常放在请求内容里。文档列出的实际接口路径包括 POST /v1/chat/completions、POST /v1/responses 和 POST /v1/messages。Base URL 是客户端配置项，不能把完整接口地址一股脑填进去。

客户端追加路径的两个正确示例和一个重复拼接反例

图：星桥 API 生成的路径知识图。api.example.com 为示例域名；各例假设客户端追加图示路径，不代表所有客户端的行为。最终以客户端文档与请求日志为准。

第一步，找到完整报错路径。 客户端有详细日志，就看最终请求到了哪个 URL；只有“404”两个字，先打开调试日志或找服务端请求记录。若看见 /v1/v1、/responses/responses，说明路径可能重复。若路径看起来正确，也别硬删 /v1，继续查客户端正在用 Chat Completions、Responses 还是 Anthropic Messages。

第二步，核对这个工具要的协议。 这里的协议，可以先理解为客户端和服务端约定的请求格式与接口。Codex CLI 按本文引用文档配置时使用 wire_api = "responses"，所选模型和分组需要支持 /v1/responses。只支持 Chat Completions 的渠道，换个 Base URL 也变不出 Responses。

Claude Code 使用 Messages。本文引用的网关文档还注明当前未启用 /v1/messages/count_tokens；若某个功能请求这个端点而报 404，应记录具体路径和工具版本。接口尚未提供，就要查工具兼容性或服务支持情况，光换密钥不对症。

第三步，再看模型和权限。 路径正确后，核对密钥可用的准确模型 ID、分组和端点。404 也可能来自不存在的资源或未实现的接口；401 更值得优先检查密钥。状态码只是线索，错误正文和请求路径才帮你缩小范围。

API 报 404 的排查路线：路径、协议、模型与权限

图：每次只改一处再验证。路径没重复，也要继续核对协议端点和模型权限。

一个最短验收办法

先在服务商文档里找对应客户端的 Base URL，抄配置项，别抄“实际请求路径”。选当前密钥有权限、且支持该协议的模型，发一条不含隐私的短请求。然后对照客户端日志、错误正文和服务端使用日志：能拿到回复且用量记录对应，才算跑通。

看不到请求路径时，把客户端版本、时间、脱敏错误正文交给管理员排查，不要发送完整 API Key。

星桥 API 网关由我们运营。上文的配置地址和协议限制来自星桥使用文档，可点文末「阅读原文」查看对应客户端的填法；其他服务商的地址与支持范围请查各自文档。

排查时记住这个顺序：看完整路径 → 查协议端点 → 核对模型与权限。一回只改一处，再发请求验证。可别一见 404 就把地址、模型、密钥全换了，整半天，好使了都不知道是哪步好使的。

资料：星桥 API 使用文档；OpenAI Chat Completions 与 Responses API 参考；Anthropic Claude Code 网关接入文档。核对日期：2026-10-28。