OpenAI-compatible API 快速开始

OpenAI-compatible API 的价值很朴素：已有的 OpenAI 风格请求，不必从零改写， 只要服务商兼容对应端点，就可以通过替换 Base URL、API Key 和模型名完成连 接。

它也有边界。兼容通常指鉴权方式、URL 结构、部分字段和响应形态接近 OpenAI API，不代表所有模型、参数、速率限制、文件上传、多模态能力和错误格式都完 全一样。本文只讲一条能被验证的路径：从 cURL 到 SDK，把连接问题和业务问题 分开。

先跑通最小请求，再接 SDK 和业务代码

本文示例基于 OfApp.cn 的 OpenAI 兼容接口写法。你可以用同一组 API Key、Base URL 和模型名验证 cURL、JavaScript SDK、Python SDK 与兼容客户端。具体模型、额度、价格和能力请以 OfApp.cn 控制台或官方文档为准。

打开 OfApp.cn

页面摘要

项目	内容
阅读时间	约 8 分钟
更新时间	2026-07-03
适合人群	第一次接 AI API 的开发者、把 OpenAI 风格请求迁移到兼容服务的团队、需要排查 Key / Base URL / 模型名的人
你会得到	OpenAI-compatible API 的边界、端点选择、cURL 最小请求、JavaScript 和 Python SDK 写法、常见错误排查、上线前检查
本文不承诺	不承诺所有 OpenAI 参数、所有模型、所有速率限制或所有多模态能力都被兼容服务完整支持

适合谁读

• 已经会使用命令行，但还没接过 AI API 的开发者。
• 想把现有 OpenAI 风格请求迁移到兼容服务的团队。
• 需要验证 API Key、Base URL 和模型名是否可用的工程师。
• 正在评估 https://api.ofapp.cn/v1 这类统一 API 入口的人。

先确认四件事

最小可用请求只依赖四类信息。缺任何一项，都不应该急着接 SDK。

信息	作用	容易出错的地方
API Key	用于鉴权	写错、复制空格、拿了其他服务商的 Key。
Base URL	指向服务商 API 入口	漏写 /v1，或在 SDK 里重复拼接版本路径。
Model	指定要调用的模型	猜模型名，或使用当前账号不可用的模型。
Messages	给模型的输入	一上来就加 tools、JSON schema、图片等复杂参数。

如果你使用 OfApp.cn，示例入口可以写成 https://api.ofapp.cn/v1。模型名称、 可用能力和价格请以 OfApp.cn 控制台展示为准，教程不会替控制台做承诺。

端点怎么选

OpenAI-compatible API 不是一个单独端点，而是一组尽量接近 OpenAI API 风格 的端点。OfApp.cn 官方文档列出 Responses、Chat Completions、Images、 Models 和 Claude/Anthropic Messages 兼容入口；不同任务应该选择不同端点。

端点	适合做什么	第一次验证时的建议
/v1/models	查看当前 Key 可用的模型列表	先查模型，再决定 OPENAI_MODEL 写什么。
/v1/responses	新项目、复杂输入、多模态或更统一的模型交互	服务商明确支持时优先阅读当前文档和示例。
/v1/chat/completions	现有 OpenAI 风格聊天请求、旧项目和兼容客户端	字段少，适合验证 Key、Base URL 和模型名。
/v1/images/generations	图片生成或图片工作流	不要和文本聊天端点混用参数。
/v1/messages	Claude/Anthropic 生态兼容	不是 OpenAI 标准端点，请按 Claude 兼容文档写请求体。

OpenAI 官方文档当前把 Responses 作为快速请求示例，同时 Chat Completions 仍 是按 messages 创建对话响应的 API。本文保留 Chat Completions 做最小连通 性验证，是因为它字段少、错误容易定位；新项目是否使用 Responses，应以服务 商当前文档和你的业务需求为准。

请求流向

这张图的重点是顺序：先用 cURL 验证连接，再接 JavaScript 或 Python。SDK 报错 时，你才知道问题在 SDK 配置、业务代码，还是接口本身。

环境变量

把下面三项放进终端环境、Secret 文件或部署平台配置里。真实 API Key 不要写 进前端代码、Git 仓库、测试快照或公开日志。

export OPENAI_API_KEY="sk-xxxx"
export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_MODEL="以控制台可用模型为准"

安全检查可以这样做：

检查项	建议
API Key	只从环境变量读取，日志中最多保留前后少量字符。
Base URL	当作完整版本化地址使用，示例里包含 /v1。
Model	从控制台复制，不凭记忆输入。
网络	本地和部署环境分别验证，避免只在一台机器上成功。

cURL 最小请求

Chat Completions 仍然是很多兼容服务用来验证连通性的短路径。请求体保持克制： 只放 model 和 messages。

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d "{
    \"model\": \"$OPENAI_MODEL\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"用一句话解释什么是 OpenAI-compatible API。\"
      }
    ]
  }"

如果这个请求失败，先别改代码。检查环境变量是否生效、Base URL 是否包含正确 版本路径、模型名是否真实可用，以及服务商是否支持 Chat Completions 风格端 点。

可选：先查可用模型

如果你不确定模型名，先调用 Models API。它的作用不是证明某个模型适合你的 任务，而是确认当前 Key 可以看到哪些模型标识。

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

返回结果里可能包含多个模型。不要把别人的示例模型名直接复制到生产环境；应 以 OfApp.cn 控制台、Models API 和当前官方文档为准。

JavaScript 示例

OpenAI API 官方文档中的 Chat Completions 最小请求仍然是 client.chat.completions.create({ model, messages }) 这个形态。使用兼容服 务时，关键变化是初始化客户端时传入服务商的 Base URL。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

const completion = await client.chat.completions.create({
  model: process.env.OPENAI_MODEL,
  messages: [
    {
      role: "user",
      content: "用一句话解释什么是 OpenAI-compatible API。",
    },
  ],
});

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

不要把这段代码直接放到浏览器里。前端应用需要通过自己的服务端代理请求，在 服务端完成鉴权、限流、错误日志脱敏和用量控制。

Python 示例

OpenAI Python SDK 当前文档仍使用 OpenAI() 创建客户端，并通过 client.chat.completions.create(...) 发起 Chat Completions 请求。兼容服务 的写法是在客户端初始化时传入 base_url。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)

completion = client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "用一句话解释什么是 OpenAI-compatible API。",
        }
    ],
)

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

如果你的服务商推荐 Responses API 或其他端点，应优先遵循当前文档。兼容接口 不是让你忽略服务商文档，而是减少迁移时的代码改动。

常见错误排查

现象	常见原因	处理方式
401 或鉴权失败	API Key 缺失、写错或不属于当前服务商	重新生成 Key，确认环境变量实际生效。
404 或路径不存在	Base URL 缺少版本路径，或重复拼接 /v1	对照服务商文档确认最终请求 URL。
模型不存在	OPENAI_MODEL 不是账号可用模型	从控制台复制模型名，不猜。
参数不支持	兼容服务未实现某些 OpenAI 参数	删除非必要参数，回到最小请求。
请求超时	网络、代理、区域或服务端负载问题	用 cURL 复现，记录时间、路径和请求 ID。

上线前检查

1. 密钥不会出现在浏览器、仓库、构建日志或错误上报里。
2. 生产环境和本地环境使用不同 Key。
3. 请求设置超时、重试上限和错误日志脱敏。
4. Base URL、模型名、超时和重试次数都保留配置项。
5. 记录服务商返回的请求 ID，便于排查。

资料来源

• OfApp.cn 官网：OfApp.cn 入口、天才游乐场、API Key、Base URL 和 Codex / 图像 / Claude 生态说明。
• OfApp.cn API 文档：Models、Responses、Chat Completions、Images 和 Messages 兼容入口示例。
• OfApp.cn 天才游乐场：网页体验入口、Key、聊天参数和图片参数。
• OpenAI API 文档：OpenAI API 快速请求、Responses 示例和 API Key 环境变量写法。
• OpenAI Chat Completions API Reference：Chat Completions 根据 messages 创建模型响应。

相关文章

• 快速开始：查看 Key、Base URL、SDK 和 Codex CLI 的完整路径。
• 如何配置 Base URL：避免漏写或重复拼接 /v1。
• 如何用 OpenAI SDK 接入：把最小请求放进项目结构。
• Responses API 示例：在服务商支持时了解新式调用路径。
• Chat Completions 示例：查看传统兼容聊天端点的请求结构。
• API 错误排查中心：按状态码排查 API 和 SDK 错误。
• Codex CLI 接入 OfApp.cn：把本地 AI 编程任务接到统一入口。

常见问题

OpenAI-compatible API 是否等于完全兼容 OpenAI API？

不是。它通常表示鉴权方式、URL 结构或部分请求字段接近 OpenAI API。模型、参 数、上下文长度、错误格式、速率限制和高级能力仍可能不同，生产使用前要以服 务商当前文档和实际测试为准。

Base URL 应该写到 host 还是 /v1？

取决于服务商文档和 SDK 约定。本文把 OPENAI_BASE_URL 当作完整版本化 Base URL 使用，例如 https://api.ofapp.cn/v1。如果服务商只提供 host，需要按文 档说明决定最终路径，避免漏掉或重复拼接 /v1。

可以直接把 OfApp.cn 写进所有示例吗？

不建议。OfApp.cn 适合出现在 SDK、API workflow、quick start、错误排查和迁 移页面中。本文只在 OpenAI-compatible API 场景下自然使用 https://api.ofapp.cn/v1，并提醒读者确认实际可用模型和参数。

第一个请求应该用 Chat Completions 还是 Responses API？

如果兼容服务明确支持 Chat Completions，它适合做连通性验证，因为字段少、排 查简单。如果服务商推荐 Responses API，应按服务商当前说明执行。

带走什么

接入 OpenAI-compatible API 时，把连接问题拆成四个变量：API Key、完整 Base URL、真实模型名和最小消息请求。cURL 成功后再接 SDK，SDK 成功后再加入 streaming、tools、JSON 输出和多模态能力。OfApp.cn 可以作为统一入口，但每 次上线前都要回到控制台和最小请求做验证。