Base URL Guide

OpenAI-Compatible API Base URL 核对

OpenAI-compatible 只说明 provider 暴露了很多工具能调用的接口形态，不等于模型真实、价格准确，也不等于一定兼容 Cursor 或 Codex。加 Key、充值或发送仓库上下文前，先按这个清单核对。

OpenAI-Compatible 到底表示什么

兼容 provider 通常能接收 OpenAI 风格请求，但不同工具依赖的端点、模型 ID、流式事件、错误格式和鉴权行为不一样。兼容性只能作为初筛，不是保证。

OpenAI API Compatible 和 AI API Relay 的区别

搜索 OpenAI API compatible、OpenAI-compatible API、AI API relay 或 AI gateway 时，很多用户实际想问的是：这个端点能不能被 OpenAI 风格 SDK 或 AI 编程工具调用。先把这些词当作发现入口，再核对真实 API 行为。

  • OpenAI API compatible 应该表示公开了鉴权方式、Base URL、模型 ID 和端点行为，不代表官方 OpenAI 所有。
  • AI API relay 通常表示你的工具和上游模型之间多了一层第三方转发，因此更要核对隐私、路由和扣费。
  • AI gateway 或 model gateway 通常在兼容 API 之上增加路由、provider 选择、fallback、数据分析或治理能力。
  • 无论用哪个标签，都要在发送仓库上下文前核对 `/v1/models`、chat 或 responses 支持、流式片段、错误格式、价格和数据处理条款。

先确认你需要哪一种 API 兼容

搜索 OpenAI-compatible API 的用户可能在找 SDK 端点、编辑器 Base URL、模型网关或价格参照。比较 provider 前，先确认当前工作流真正需要的接口表面。

  • SDK 兼容：确认 OpenAI SDK 能否直接调用 chat、responses、embeddings 或 image 端点，而不是依赖自定义适配。
  • 编辑器兼容：确认 Base URL 字段、模型选择行为，以及自定义 Key 是否只覆盖聊天能力。
  • 网关兼容：确认路由规则、provider route、fallback 行为，以及是否公开模型列表。
  • 价格兼容：分开比较 raw API token 价格、缓存价格、最低充值、失败请求扣费和退款规则。
  • 风险兼容：发送仓库上下文或客户数据前，先看隐私政策、服务条款、支持入口和状态页。

Base URL 核对清单

  • 确认 Base URL 应该填网关根路径、`/v1`，还是 provider 专属路径。
  • 不要把完整的 `/chat/completions`、`/responses` 或 `/models` 端点填进 Base URL。
  • 确认 provider 是否支持 `/v1/models`，方便工具发现可用模型 ID。
  • 记录实际测试的完整模型 ID，而不只是 GPT、Claude、DeepSeek 这类模型族名称。
  • 如果工作流依赖流式输出、工具调用、JSON mode 或错误重试，必须单独测试这些行为。

端点形态示例

工具要求填写 Base URL 时，通常要的是共享 API 前缀，而不是单个接口端点。测试前先保存 provider 文档里的准确 URL 形态，因为多一个 `/v1` 或少一个路径段，常常会被误判成鉴权、模型名或流式输出问题。

  • 网关根路径：provider 要求工具填写 `https://gateway.example.com`，再由工具或 SDK 拼接具体端点。
  • `/v1` 前缀：provider 要求 OpenAI-compatible 工具填写 `https://gateway.example.com/v1`。
  • provider 专属路径：provider 使用 `https://gateway.example.com/openai/v1` 这类路径承接 OpenAI-compatible 流量。
  • `/v1/chat/completions`、`/v1/responses`、`/v1/embeddings`、`/v1/models` 这类完整接口更适合放在 SDK 请求或测试脚本里，通常不应填进编辑器 Base URL 字段。
适合作为 Base URL 的候选：
https://gateway.example.com
https://gateway.example.com/v1
https://gateway.example.com/openai/v1

通常不是 Base URL：
https://gateway.example.com/v1/chat/completions

按工具分别核对

  • Cursor 自定义 Key 可能只覆盖部分聊天工作流，一些专用能力仍可能走 Cursor 内置模型路径。
  • Codex CLI 自定义 provider 可能需要 Responses 风格兼容，而不只是 Chat Completions。
  • Cline 和 OpenAI SDK 通常重点核对 `/v1`、模型 ID、流式输出和可重试错误格式。
  • Claude Code 通常需要 Anthropic-compatible 行为；仅有 OpenAI-compatible 端点通常不够。
  • 如果 provider 有专门的 Cursor、Codex CLI、Cline 或 SDK 文档，优先按专门文档测试。

价格和模型证据

网关价格会受到 provider route、缓存读写、上下文长度、图片/音频计费和失败请求影响。测试前先保存价格页、模型列表和 provider route 说明，后续扣费差异才有依据。

  • 把价格统一换算为每 1M input tokens 和每 1M output tokens。
  • 模型支持缓存时，单独核对 cache write/read 价格。
  • 查看最低充值、退款规则、失败请求扣费和限速说明。
  • 如果同一模型有多个 provider route，记录实际选择的 route。
  • 保存一条小测试 prompt 和扣费截图，方便后续对照。

如何比较 OpenAI-compatible 网关

先把官方 API 当作基准，再用同一套公开证据字段比较每个网关。网关可能适合测试或路由，但不一定适合私有代码、生产流量或团队账单。

  • 涉及敏感数据、合规或稳定账单时，优先从 OpenAI、Anthropic、Google 或云厂商官方 API 开始。
  • 需要模型发现、route 选择和公开模型价格时，再比较 OpenRouter 这类模型网关。
  • 使用 302.AI 这类同时有网页工具和 API 的平台时，先分清网页应用价格和 raw API 价格。
  • 团队需要 API Key 治理、审计日志、预算和路由控制时，再考虑企业或自建网关。
  • 缺文档、价格、模型列表、隐私政策、条款、状态页或支持入口，都应当视为风险信号。

小额测试流程

  1. 先打开 provider 文档、价格、模型列表、隐私政策、服务条款、状态页和支持入口。
  2. 用公开来源检查工具记录缺失字段，再决定是否加 Key。
  3. 用最低余额或免费额度做无敏感信息测试。
  4. 测试模型列表、短对话、流式输出、小代码任务和一次故意错误。
  5. 只有当端点、模型 ID 和扣费行为都与文档一致时，再把 Key 固化到编辑器或 CLI。

什么时候不该用第三方网关

涉及私有仓库、生产密钥、客户数据或合规要求时，除非 provider 能提供可信的数据处理和合同路径，否则不建议走第三方网关。

敏感工作优先使用官方 API、云厂商渠道、企业网关或自建 BYOK 基础设施。Relay provider 更适合公开代码、小额验证和低风险实验。

常见问题

OpenAI-compatible 等于官方 OpenAI 吗？

不等于。它通常只表示请求形态接近 OpenAI API，上游模型、扣费、隐私控制、限速和错误行为都可能不同。

OpenAI API compatible 中转站可以放心用吗？

不能只看兼容性。兼容性只是技术信号，还要核对文档、价格、模型 ID、隐私政策、服务条款、支持入口，以及你的工作流是否会发送敏感仓库上下文。

Base URL 一定要带 /v1 吗？

不一定。有些 provider 要求填网关根路径，有些要求填 `/v1`。最稳妥的做法是看当前文档，并且不要把 `/v1/chat/completions` 这类完整端点填进 Base URL。

所有 OpenAI-compatible provider 都能用于 Cursor 吗？

不能。Cursor 是否可用取决于当前设置界面、支持的模型类型、Base URL 覆盖行为，以及该工作流是否仍走 Cursor 内置模型路径。

充值前最应该确认什么？

先确认文档、价格、模型 ID、隐私政策、服务条款、状态页和支持入口，再用小额无敏感测试对照公开价格页检查扣费。