什么是 OpenAI-Compatible API？Base URL、API Key 与模型配置指南
OpenAI-compatible API 让开发者可以用相同的客户端模式接入不同模型服务。本指南从开发者角度解释 base URL、API key、模型名称、Cursor/CLI 配置以及兼容性的真实边界。
· CodeFast Team
OpenAI-compatible API 是什么意思？
许多 AI 应用遵循相同的基本流程：发送消息、指定模型名称、选择是否 streaming，并接收响应。OpenAI-compatible API 将这个流程变成一种共同约定。因此客户端 SDK、agent framework、CLI 工具或编辑器插件可以用同一种对话格式连接不同端点。
兼容并不意味着每个供应商行为完全一致。更准确的说法是：请求和响应结构足够相似，因此开发工具可以用最少配置运行。这也是 OpenAI-compatible 方式适合 Cursor、终端工作流、后端服务和模型对比流程的原因。
为什么 base URL 如此重要？
Base URL 决定客户端把请求发送到哪个 API 层。当你把默认 OpenAI 地址替换成 CodeFast 等其他端点时，客户端保持相同格式，但流量会被路由到另一个供应商或 gateway 层。这个小配置变化，是在不扩大应用代码的情况下扩展模型选择的实用方式。
Provider: OpenAI Compatible
Base URL: https://api.codefast.app/open-source-api/v1
API Key: cf_live_your_api_key
Model: selected-model-for-your-workflow
OpenAI-compatible 客户端的典型配置方式
实际使用时，最重要的是三个字段。Base URL 定义连接到哪里，API key 定义使用哪种访问权限，模型名称定义调用哪种能力。三者正确时，客户端通常可以保持同样的 chat/completions 工作流。
它适用于哪些工具？
- 在 Cursor 或类似编辑器中定义 custom provider 时。
- 在 CLI 工具中用相同命令习惯测试不同模型时。
- 当后端服务希望通过配置而不是重写代码切换供应商时。
- 在 A/B 测试中比较不同模型家族的质量、速度和成本时。
需要注意的兼容性边界
OpenAI-compatible 格式可以加速基础聊天流程，但不保证每个特殊功能都以相同方式运行。Tool calling、vision、reasoning 参数、token 统计、错误码和 streaming 分片可能因供应商而异。因此在生产环境中，不仅要测试连接是否成功，还要测试响应行为是否符合预期。
- 先用简单 chat 请求验证连接。
- 然后分别测试 streaming、长上下文和错误状态。
- 按照当前文档列表使用模型名称。
- 生产使用前明确限制、timeout 和 fallback 策略。
这和 AI API Gateway 有什么关系？
OpenAI-compatible API 是一种客户端格式；AI API Gateway 是更大的访问层，用来同时管理这种格式、权限、套餐和不同模型端点。换句话说，gateway 将 OpenAI-compatible 工作流产品化：一个面板、一套 API key 模式、多种模型家族和用量可见性集中在一起。
使用 CodeFast 的实际方式
在 CodeFast 中，OpenAI-compatible 端点让开发者可以用相同工作习惯测试不同 API 套餐。Open Source API、Qwen API、Grok API 或 GLM API 等套餐会在文档中清楚列出 base URL 和模型名称。你从面板获取 API key，在客户端配置 provider，然后发送测试请求。