OpenAI Compatible API 教程：Base URL、SDK 与调用验证

OpenAI Compatible API 的价值，在于让现有 SDK、脚本和工具通过统一协议连接不同模型。迁移时通常不需要重写业务逻辑，重点是确认 Base URL、API Key、模型 ID 和接口类型。

直接答案

接入 OpenAI Compatible API 时，先把 Base URL 配置为服务商文档给出的地址，再用同一个 API Key 请求 /v1/models，复制返回的真实模型 ID，最后发送一条 stream: false 的短请求。若最终地址出现 /v1/v1、返回 HTML 或模型列表中的 ID 不可用，先修复 Base URL、认证或模型权限，再继续测试 SSE 和工具调用。

AIFast Link 的协议与月卡接入顺序

Link 的 OpenAI SDK 基础地址是 https://www.aifast.link/v1。Claude Code 使用的是 https://www.aifast.link，Messages 请求最终到 /v1/messages；不要把这两个字段按同一种拼接规则填写。图像生成模型也不能直接当作聊天或 Codex 编程模型。

先在 Link 模型广场确认目录，再用自己的 Key 查询可用模型。月卡用户还应确认 Key 的分组与套餐范围一致；成功返回一次文本后，到用量日志核对计费来源，再启用重试或批量请求。

查看 Link 充值与月卡规则

OpenAI Compatible API 怎么接入和测试？

先按下表准备配置与验收证据，再运行后面的 curl、Python 或 Node.js 示例。

这张表只定义验收顺序，不代表任何平台的模型或高级能力都必然兼容。

OpenAI Compatible API 的 Base URL 应该怎么填？

OpenAI SDK 会在 Base URL 后追加模型列表和聊天端点。常见版本路径是 /v1，完整示例为 https://www.aifast.link/v1。如果客户端明确说明会自行追加版本路径，则只填写域名。判断标准不是配置框的名称，而是诊断日志中的最终请求地址。如果地址出现 /v1/v1，说明版本路径被重复拼接；返回网页首页也不是有效 API 响应。

打开 Base URL 检查器

OpenAI Compatible API 怎么测试？

不要只看 HTTP 状态码。用下面的结果对照定位失败阶段，避免继续增加无关参数。

需要协议与行为信号的抽样结果时，可运行模型质量检测；完整能力清单见接口兼容性核验。检测结果不是厂商身份认证或长期 SLA。

开始前检查

准备以下三项：

1. 在 AI快站控制台创建的 API Key。
2. 接口基础地址 https://www.aifast.link/v1。
3. 控制台模型广场中显示的真实模型 ID。

API Key 只会在创建时完整显示。不要把它写入公开仓库、前端代码、截图或聊天记录。

配置步骤

1. 先查询模型列表

在终端执行：

curl https://www.aifast.link/v1/models \
  -H "Authorization: Bearer $AIFAST_API_KEY"

如果成功返回包含 data 数组的模型列表响应，说明域名解析、HTTPS 和身份验证链路基本正常。如果返回 401，先检查 Key；如果返回 HTML 页面，通常是 Base URL 写错或请求没有进入 API 路由。

用 curl 发送一条最小聊天请求

下面是可自行执行的请求示例，不是本站已完成的模型实测。先在本机安全设置 AIFAST_API_KEY，并把 YOUR_MODEL_ID 替换为同一 Key 可用、且明确支持 Chat Completions 的文本模型 ID。实际执行可能计费；只发一条短请求，不开启自动重试，也不要在未确认权限前批量运行。

: "${AIFAST_API_KEY:?Set AIFAST_API_KEY locally before running}"
curl --request POST \
  --connect-timeout 10 --max-time 30 \
  --silent --show-error --include \
  https://www.aifast.link/v1/chat/completions \
  --header "Authorization: Bearer ${AIFAST_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-raw '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Reply with OK only."}],"stream":false}'

先看响应头的 HTTP 状态和 Content-Type，再看 JSON 中的 choices、message、finish_reason 与 usage。HTTP 200 只是必要检查之一；错误对象、空 choices 或缺少预期文本不能算成功。记录用量字段缺失，不要把未知用量填成 0。此请求仅测试 Chat Completions，不证明 Responses、工具调用或所有模型都可用。

若超时或连接中断，先查用量日志再重试；客户端超时不代表服务端未处理或没有计费。支持服务不需要完整 Key，分享诊断前删除 Authorization、Cookie、客户提示词和个人信息。

Chat Completions、Responses 和 Messages 有什么区别？

OpenAI Compatible 表示特定接口形状兼容，不等于所有客户端、模型和功能自动兼容。按实际任务选择下表中的接口，每行单独验收；这些是请求结构示例，不是当前账号的能力保证。

模型列表能读到一个 ID，不代表上面每个端点都支持它。Gemini 原生 generateContent 也不是这三种请求体的别名，应按独立协议配置。

查看 Link Gemini 协议与分组说明

继续配置 SDK

2. 使用 Python SDK

安装 SDK：

python -m pip install --upgrade openai

把 Key 放进环境变量：

export AIFAST_API_KEY="你的_API_Key"

最小调用示例：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIFAST_API_KEY"],
    base_url="https://www.aifast.link/v1",
    max_retries=0,
    timeout=30.0,
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[
        {"role": "user", "content": "用三句话解释什么是提示缓存。"}
    ],
)

print(response.choices[0].message.content)

将 YOUR_MODEL_ID 替换为模型广场中的真实模型 ID，不要填写卡片标题、中文别名或厂商名称。

3. 使用 Node.js SDK

npm install openai
export AIFAST_API_KEY="你的_API_Key"

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AIFAST_API_KEY,
  baseURL: "https://www.aifast.link/v1",
  maxRetries: 0,
  timeout: 30_000,
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [
    { role: "user", content: "列出 API 上线前需要检查的五项配置。" },
  ],
});

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

4. 不要重复拼接 /v1

不同客户端对 Base URL 的处理方式不同：

如果日志里出现 /v1/v1/chat/completions，说明客户端和配置各追加了一次 /v1。

常见问题

返回 401 Unauthorized

• Key 前后是否多了空格或引号。
• 是否误用了已删除、过期或属于其他账号的 Key。
• 请求头是否为 Authorization: Bearer YOUR_KEY。

返回 model not found

• 先调用 /v1/models 获取真实模型 ID。
• 不要把网页展示名称当作接口模型名。
• 确认模型是否对当前账号开放。

流式输出中断

先关闭流式模式做一次短请求。如果非流式请求正常，再检查客户端读取超时、代理缓冲和网络连接，而不是直接更换模型。

下一步

第一次请求成功后，再逐步加入流式输出、重试、超时、日志和模型路由。不要在尚未验证基础调用时一次性接入所有高级参数。

查看 401、429、502 API 错误排查，或前往 AI快站模型广场 确认当前可用模型。

需要核对 AI快站当前域名、Base URL 或平台运营声明时，请回到平台事实、官方入口与验证边界查看证据类型和最后验证日期。

2026-10-11 验证记录：先区分认证入口与模型调用

本次对 Link 公网入口执行了两项不带 Key 的 GET 请求：/api/status 返回 200 JSON，/v1/models 返回 401 JSON，错误类型为 new_api_error。401 在这个对照中是预期的认证拒绝，不能当成模型离线；这两项结果也不能证明带 Key 的模型调用、流式输出或工具调用成功。

可先运行下面的不带 Key 对照。若收到 HTML、验证码页面或超时，先处理网络和 API 路径；不要把这些响应当作模型 JSON 交给 SDK。对照通过后，再在自己电脑设置独立限额 Key，按上文示例验证模型列表和短请求。

curl --connect-timeout 10 --max-time 30 -sS \
  -o aifast-auth-check.json -w "%{http_code}\n" \
  https://www.aifast.link/v1/models

最小迁移记录应保留哪些内容

先记录 python -m pip show openai 或 npm ls openai 的版本输出。固定同一个 Key、模型 ID、分组与短提示词，只改变 Base URL；初次排错关闭自动重试并设置 30 秒超时。若需要比较更慢的模型，再单独调整超时并记录，避免重复请求被误当成一次调用。

成功样本应记录最终端点、HTTP 状态、返回模型、结束原因、usage，以及 Link 用量日志中的最终消耗和计费来源。预扣金额不是最终消耗；响应能生成文字，也不能证明 SSE、Responses、图片或 Agent 的所有能力都兼容。截图和公开记录必须去掉 Key、客户提示词及个人信息。

本节只发布上述认证入口实测结果与迁移验收方法，没有把未执行的付费请求或 SDK 调用写成成功案例。