做 API 中转接入时，真正让人卡住的往往不是模型能力，而是 Base URL 怎么写、鉴权头怎么拼、超时设多少。任何一项不一致，都会以 401、404、超时或空响应的形式出现，看起来像服务故障，实际是配置问题。

这篇清单按「接入顺序」梳理：先确认入口与协议，再处理 Base URL，接着核对鉴权，最后调整超时与重试。每一步都给出可执行的检查方法，适合刚从中转平台拿到 Key、准备调用万相类生成模型的开发者对照排查。

一、接入前先确认三件事

在写第一行代码之前，建议先把下面三项记录下来，避免来回试错：

• 接口地址（Base URL）：以控制台展示的地址为准，注意是否需要带 /v1 后缀。
• 鉴权方式：多数中转平台兼容 OpenAI 风格的 Authorization: Bearer <API Key>，但不同协议方向的具体写法可能有差异。
• 模型名称：不要凭记忆写缩写，直接从模型广场复制页面上显示的完整名称。

这三项只要有一项与平台实际配置不一致，后面的代码写得再规范也没用。在 通联AI中转站 的控制台里，接口地址、模型名称与 API Key 都在同一处可查，先复制再动手是比较稳妥的做法。

二、Base URL 的四个高频坑

坑 1：把完整请求路径当成了 Base URL

多数 SDK 会在 Base URL 后面自动拼接 /chat/completions 之类的路径。如果你把完整地址写进 Base URL，最终请求路径会重复拼接一次，服务器返回 404，而报错信息往往只说「接口不存在」，让人误以为地址整体写错。

坑 2：结尾斜杠与重复路径

部分客户端会用 / 把 base 和 path 连起来。base 以斜杠结尾时就可能出现双斜杠。多数网关能容忍，少数会直接报 404，因此建议统一去掉结尾斜杠，保持一种写法贯穿所有环境。

坑 3：环境变量没生效

本地调试时改了环境变量，但虚拟环境、容器或 CI 里仍是旧值，报错看起来却像 Key 错误。修改配置后重启进程，并打印一次实际读取到的地址，能快速排除这类问题。

坑 4：混淆了对话与生成类接口

对话、图像、视频生成类接口可能挂在同一 Base URL 下，也可能分属不同路径。请以控制台或文档给出的完整接口说明为准，不要凭旧项目经验直接迁移。接入万相这类生成模型时，尤其要先确认它走的是同步返回还是「提交任务—轮询结果」的异步流程。

三、鉴权：Key 正确也可能被拒

最常见的鉴权问题不是 Key 错，而是格式错。排查时按顺序检查下面几点：

• 请求头是否带上了 Bearer 前缀，前缀后是否只有一个空格；
• Key 从网页复制时是否带入了换行、空格或不可见字符；
• 是否把不同项目、不同环境的 Key 混用；
• Key 是否曾出现在前端代码或公开仓库中，若已泄露应尽快在控制台重置。

返回码也能提供线索：401 优先怀疑 Key 与鉴权头本身；403 则更可能与权限范围、模型是否开通或余额状态有关。把两者混在一起排查，很容易在错误方向上浪费时间。

鉴权失败时，先只发一个最小请求：单条消息、短文本、不开流式、不带额外参数。确认链路通了再逐步叠加参数，能省掉大量猜测时间。

四、超时与重试：对话模型和生成模型要分开设

对话类请求通常在几秒内返回，超时可以设得相对紧凑；而图像、视频生成类任务耗时更长，且多数采用异步模式。用同一套超时参数去套所有接口，很容易出现「任务其实已经提交成功，客户端却先超时了」，随后重试又生成了重复任务。

比较稳妥的做法是把超时拆成三层：连接超时、读取超时、任务轮询总时长。同时区别对待重试——对非幂等的生成类请求，盲目重试可能带来不必要的消耗。

五、可直接照着走的排查顺序

1. 用一个最小请求验证鉴权与地址是否可用；
2. 请求成功后再切换到目标模型名称，确认模型本身可调用；
3. 逐步加入流式、温度、图片或视频相关参数，观察返回结构变化；
4. 最后调整超时与重试策略，并记录任务 ID 便于对账；
5. 把验证通过的配置写入环境变量，避免硬编码在业务代码中。

六、统一接入能减少哪些维护成本

当项目需要同时用到对话、图像、视频、语音等多类能力时，逐个平台维护 Key、地址和超时策略会迅速变成负担。通联AI中转站在这一环提供的是统一入口：一个 Base URL 接入多模型，API Key 与余额集中管理，模型名称在模型广场统一查看。对于需要在中转层做模型切换、按任务选型的团队，这能省下不少配置文件维护时间。

也需要说明一点：任何中转方案的可用模型、协议兼容方向与计费规则都可能调整。动手前请以 通联官网 控制台与文档中显示的实时信息为准，不要长期依赖某一份截图或旧文章里的参数，尤其是模型名称和接口地址这两项。