OpenAI 兼容 API 指南：更换 Base URL

了解 OpenAI 兼容 API 覆盖哪些能力，如何把现有客户端切换到 Modelflare，以及生产流量接入前需要验证哪些边界。

OpenAI 兼容 API 的核心价值，是让现有客户端继续使用熟悉的鉴权方式、JSON 请求结构和流式响应模式，同时把流量切换到另一个模型网关。迁移有时只需要替换 Base URL 和 API Key，但“兼容”始终是一份协议契约，并不代表每个模型都支持所有端点，也不代表所有供应商私有字段都能自动互转。

这篇指南适用于已经使用 OpenAI 风格 API 的应用、脚本和 AI 工具，重点说明如何安全地完成迁移。

OpenAI 兼容具体覆盖什么

最常见、最容易复用的契约包括：

  • 通过 Authorization 请求头使用 Bearer Token 鉴权；
  • 在带版本的 /v1 端点上发送和接收 JSON；
  • 使用 /v1/models、/v1/chat/completions、/v1/responses 等常见端点；
  • 对已支持的流式请求使用 Server-Sent Events；
  • 在对应协议中使用 model、messages、input、stream 和工具定义等字段。

兼容并不意味着一个模型可以在 Chat Completions 与 Responses 之间随意切换。某个模型可能只在已经验证的协议上开放。供应商私有的推理、搜索或多模态字段，也可能要求原样透传，而不是由网关做格式转换。

准备接入前，应以实时的模型与价格页面为准，确认模型、分组和 API 格式。

迁移前的准备

修改应用代码前，先完成以下检查：

  1. 在 API Keys 中为当前应用创建独立 Key，不要复用个人工具或其他环境的 Key；
  2. 选择一个能够访问目标模型的主分组；
  3. 只有在回退分组也支持同一模型，并符合成本与稳定性策略时，才按顺序添加；
  4. 记录现有端点、模型 ID、流式设置和工具调用方式，便于迁移前后对照。

Modelflare 的标准 OpenAI 兼容 Base URL 是：

https://modelflare.dev/v1

大多数 SDK 希望 Base URL 截止到 /v1，随后由 SDK 自己追加 /chat/completions 或 /responses。不要在没有确认客户端行为时重复拼接端点。

先验证鉴权和模型权限

把 API Key 放进环境变量，不要写入源码：

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

然后确认这个 Key 能读取可用模型：

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

成功响应可以证明域名、TLS 路径和 Key 有效，但还不能证明所有返回模型都支持你准备使用的请求格式。下一步必须针对真实端点发请求。

用目标协议发送第一条请求

对于明确支持 Chat Completions 的模型：

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "请回复当前使用的模型名称。"}
    ],
    "stream": false
  }'

对于支持 Responses 的编程模型：

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "请回复当前使用的模型名称。",
    "stream": false
  }'

模型 ID 必须与实时目录中显示的一致。出现 model_not_found 时，通常应检查 Key 和分组是否有模型权限，而不是只尝试修改大小写。

单独验证流式响应

非流式请求成功，并不能证明依赖流式输出的应用已经可用。把请求改为 "stream": true 后，还要确认事件逐步到达，并确认客户端没有把完整响应缓冲完才展示。

排查流式请求慢时，应拆开观察：

  • 鉴权和路由选择耗时；
  • 等待上游响应头的耗时；
  • 等待第一段有效文本或工具事件的耗时；
  • 可见输出开始后的生成速度。

Modelflare 的用量日志会保留这类单请求时序元数据，但不会保存提示词、响应正文、原始请求体、API Key、邮箱或明文 IP。

生产迁移检查表

  • API Key 存放在 Secret 管理系统或环境变量中；
  • Base URL 固定为 https://modelflare.dev/v1；
  • 模型明确支持所选端点；
  • 非流式和流式模式分别验证；
  • 应用使用工具、结构化输出、推理参数或多模态输入时，逐项验证；
  • 对有语义的 0 和 false 保持显式传递；
  • 客户端超时按真实工作负载设置，而不是按一条短健康检查设置；
  • 切换后在用量日志中检查状态、延迟、Token、所选分组和费用。

协议边界验证通过后，客户端通常可以保留原有请求生命周期，由 Modelflare 在兼容端点之后提供模型访问、路由策略和单请求可观测性。