AI API 中转站接入前必须核对的 6 个配置项

第一次接入 AI API 中转站时，最浪费时间的做法不是“不会写代码”，而是拿到一个报错后反复更换模型、重装 SDK、修改代理，却没有先确认请求到底发向哪里、使用什么协议、当前令牌能看到哪些模型。

一个接口能打开官网，不等于模型请求已经打通；/v1/models 能返回，也不等于流式输出、工具调用和目标模型一定可用。接入前把下面 6 个配置项按顺序核对，通常可以在真正写业务代码前排除大部分 401、403、404、model not found 和 429 问题。

本文面向正在接入 OpenAI 兼容 API、AI 编程工具或自建网关的开发者。示例使用 FishAI API 的公开入口 https://yufish.cc，密钥和模型名全部使用环境变量，不展示任何真实凭据。

一张表看完：接入前检查什么

1. 先确认协议，不要只看模型名称

“模型叫 Claude”不代表客户端一定发送 Anthropic Messages 请求；“支持 OpenAI SDK”也不代表自动支持 Responses API。真正决定请求格式的是客户端使用的协议。

常见组合如下：

• OpenAI SDK 的 chat.completions.create 通常请求 /v1/chat/completions；
• 新版 Agent 或 Codex 类客户端可能使用 /v1/responses；
• Claude Code 通常需要 Anthropic Messages 兼容接口；
• Gemini CLI 或 Gemini SDK 可能使用 Gemini 原生的 generateContent 路径。

接入前先回答两个问题：客户端实际调用哪个接口？中转站是否支持这个接口和目标模型的转换？如果只确认“平台里有这个模型”，没有确认协议，后面即使模型名完全正确也可能失败。

2. Base URL 要和客户端的自动拼接规则配套

OpenAI 兼容 SDK 常见的版本根地址是：

https://yufish.cc/v1

但并不是所有客户端都要求把 /v1 写进 Base URL。有些客户端会自动追加版本路径；如果配置中再次加入，就可能得到：

https://example.com/v1/v1/chat/completions

排查 404 时，不要先换模型。先在调试日志、代理日志或浏览器网络面板里查看最终完整 URL，确认没有路径重复、缺失或仍然指向客户端默认域名。

3. API Key 不只要“填对”，还要被当前进程读取

密钥建议只通过环境变量或服务端密钥管理注入。下面是一份最小环境配置：

export FISHAI_API_KEY="sk-placeholder"
export FISHAI_BASE_URL="https://yufish.cc/v1"
export FISHAI_MODEL="从模型列表复制的精确模型 ID"

这里的 sk-placeholder 只是占位符。不要把真实 Key 写进文章、前端代码、Git 仓库、截图或共享日志。

修改环境变量后，还要确认启动应用的进程能读取它。常见误区是：终端 A 中设置了变量，却从 IDE、系统服务或另一个终端启动程序。此时“变量存在”不等于目标进程已经继承。必要时完全退出旧进程再启动，并只输出变量是否存在，不输出完整值。

OpenAI 兼容接口通常使用：

Authorization: Bearer <API_KEY>

如果返回 401，优先检查 Key 是否为空、是否带多余空格、是否被旧配置覆盖；如果返回 403，则继续检查令牌状态、模型权限和分组权限。

4. 模型 ID 和令牌分组必须一起核对

模型列表是当前令牌可见范围的快照，不要凭宣传页、旧截图或记忆填写模型名。先请求模型列表，再从返回值复制精确 ID。

curl -fsS "$FISHAI_BASE_URL/models" \\
-H "Authorization: Bearer $FISHAI_API_KEY"

多模型中转站通常还有分组、渠道和定价规则。同一个模型可能在不同分组下对应不同上游、倍率和可用状态；令牌能看到模型，不代表它能访问任意分组。遇到“无可用渠道”或“当前分组不可用”时，应检查令牌绑定的分组，而不是不断重试同一个请求。

下面是一段 2026-09-01 08:48（Asia/Shanghai）对 FishAI /v1/models 发起的真实、只读、无密钥请求。它没有产生模型调用，也没有暴露任何用户凭据：

HTTP/2 401
content-type: application/json; charset=utf-8
x-oneapi-request-id: 202609010048210295704348268d9d6uFZiENHJ

{"error":{"code":"","message":"Invalid token (request id: 202609010048210295704348268d9d6uFZiENHJ)","type":"new_api_error"}}

这份日志能确认三件事：公开域名和 /v1/models 路径可达；接口确实执行了鉴权；缺少有效令牌时返回 401，而不是 404。它不能证明某个模型可以真实生成，也不能证明任何分组当前可用。加入有效令牌后，仍要继续完成模型列表和最小生成请求两层验收。

5. 在发送请求前写清额度、限流和超时边界

第一次验证的目标是证明链路正确，不是测试最大输出能力。建议使用短输入、较小输出限制、单并发和明确超时。

至少核对：

• 账户是否有可用余额或额度；
• 目标模型按量还是按次计费；
• 当前令牌和分组的速率、并发限制；
• 客户端超时与反向代理超时是否冲突；
• 失败重试是否有次数上限和退避；
• 日志是否会意外记录完整 Key 或敏感提示词。

429 不一定表示整个中转站不可用。它可能来自本地重试过快、令牌频率限制、当前分组拥堵或具体上游限流。正确做法是保存响应时间、错误体、模型和请求 ID，降低频率后再判断故障层级，而不是无上限自动重试。

6. 按“模型列表 → 非流式短请求 → 高级能力”验收

先用一个最小非流式请求验证鉴权、路径、模型和基础响应结构：

curl -fsS "$FISHAI_BASE_URL/chat/completions" \\
-H "Authorization: Bearer $FISHAI_API_KEY" \\
-H "Content-Type: application/json" \\
–max-time 30 \\
-d "{\\
\\"model\\": \\"$FISHAI_MODEL\\",\\
\\"messages\\": [{\\"role\\": \\"user\\", \\"content\\": \\"只回复 OK\\"}],\\
\\"stream\\": false,\\
\\"max_tokens\\": 16\\
}"

随后在 SDK 中复测，并给网络请求设置明确超时：

import OpenAI from "openai";

const client = new OpenAI({
apiKey: process.env.FISHAI_API_KEY,
baseURL: process.env.FISHAI_BASE_URL,
timeout: 30_000,
maxRetries: 1,
});

const response = await client.chat.completions.create({
model: process.env.FISHAI_MODEL,
messages: [{ role: "user", content: "只回复 OK" }],
stream: false,
max_tokens: 16,
});

console.log(response.choices[0]?.message?.content);

基础请求成功后，再分别测试流式输出、工具调用、图片或长上下文。把这些能力分开验收很重要：普通文本成功只能证明基础链路正常，不能证明每一种高级能力都由目标模型、协议转换层和上游共同支持。

常见报错的最短排查路径

401：先查密钥和进程

确认环境变量是否被当前进程读取、Bearer 头是否存在、Key 是否完整。不要在日志里打印完整 Key。

403：再查权限和分组

确认令牌是否启用、是否允许访问目标模型与目标分组。能登录控制台不等于令牌有模型调用权限。

404：查看最终 URL 和协议

重点检查 /v1 是否重复或缺失，以及客户端请求的是 Chat Completions、Responses、Messages 还是 Gemini 原生接口。

model not found：重新拉取列表

使用当前令牌调用模型列表并复制精确 ID。不要用旧文章或旧截图中的模型名作为长期配置。

429：停止无上限重试

记录请求 ID、错误体、分组和时间，降低并发并增加退避，再区分是客户端、网关、分组还是上游限流。

非流式成功、流式失败

检查客户端版本、代理缓冲、连接超时、SSE 事件结构和目标模型的流式支持，不要把它误判为 Key 无效。

最终验收清单

• 已确认客户端协议和实际接口路径；
• 已确认 Base URL 不会重复拼接版本路径；
• Key 通过环境变量注入，当前进程确实可读；
• 模型 ID 来自当前令牌的实时模型列表；
• 已核对令牌分组、额度、计费、限流和超时；
• 已完成一次非流式短请求，并保存状态码、响应结构和调用记录；
• 流式、工具调用等高级能力已独立验收；
• 日志、截图和仓库中没有完整密钥。

接入 AI API 中转站时，最有效的顺序不是“报错就换模型”，而是先确认协议和完整 URL，再确认进程中的 Key、模型与分组，最后用最小请求逐层验收。这样不仅能更快定位问题，也能避免无限重试、密钥泄露和不可控费用。

FishAI API 的接口路径、快速开始和工具配置可查看官方文档：https://yufish.cc/docs/。模型与价格会变化，正式使用前应以当前模型市场和实时接口返回为准。