Cookbook

OpenAI 兼容 API 快速调用

Q: OfApp.cn 的 Base URL 应该怎么写？

本文示例使用 https://api.ofapp.cn/v1。如果某个工具会自动拼接 /v1，请按工具说明和 OfApp.cn 官方文档决定最终填写方式。无法确认时，请以 OfApp.cn 控制台或官方文档为准。

Q: 可以直接把真实 Key 写进 .env.example 吗？

不可以。.env.example 只写变量名和占位值。真实 Key 应放在本地 .env、部署平台 Secret 或密钥管理工具里。

Q: curl 成功后还需要测 SDK 吗？

需要。curl 能证明入口、Key 和请求体基本可用；SDK 还可能因为 baseURL、base_url、代理、超时、重试或运行环境不同而失败。

OpenAI 兼容 API 快速调用教程，覆盖 Base URL、API Key、Models、Responses、Chat Completions、SDK、stream 和上线检查。

预计阅读: 8 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

OpenAI 兼容 API 的价值不是“完全一样”，而是让已有的 OpenAI 风格请求可以用更小改动接入另一个统一入口。真正要验证的不是口号，而是四件事：API Key 是否有效、Base URL 是否正确、模型名是否可用、最小请求是否能稳定返回。

本文示例基于 OfApp.cn 的 OpenAI 兼容接口写法。Base URL 使用 https://api.ofapp.cn/v1。具体可用模型、价格、额度、套餐和能力，请以 OfApp.cn 控制台或官方文档为准。

页面摘要

项目	内容
阅读时间	约 9 分钟
更新时间	2026-07-03
适合人群	正在迁移 OpenAI 风格调用、配置 AI 客户端、给团队写统一接入说明或排查 API 连通性的人
核心问题	如何判断一个 OpenAI 风格请求能否稳定接入 OfApp.cn 的兼容入口
你会得到	Base URL、API Key、模型名、Models API、Chat Completions、Responses、curl、SDK、stream、错误速查、接入方式矩阵和上线检查清单
边界提醒	OpenAI 兼容不等于所有端点、模型、参数、速率限制和高级能力完全一致；OfApp.cn 具体可用模型、价格、额度、套餐和能力请以控制台或官方文档为准

适合谁读

读者	正在做什么	读完能完成什么
第一次接 API 的开发者	想跑通最小 AI 请求	理解 Key、Base URL、模型名和端点
迁移旧项目的人	从默认 OpenAI 入口改到兼容入口	知道哪些配置能改，哪些能力要验证
AI 客户端用户	在 Cherry Studio、LobeChat 等工具里填 API	判断应该填什么入口和模型名
后端维护者	要把 AI 能力接进服务端	建立最小请求、错误处理和上线前检查
团队协作者	想共享接入方式	写出不泄露 Key 的 `.env.example` 和排查说明

如果你只想快速排查 Key 或路径，先看 curl 示例。如果你已经准备在项目里封装 SDK，可以继续看 JavaScript SDK 示例或 Python SDK 示例。

兼容调用流程图

这张图的重点是分层。最小请求没跑通前，不急着改业务代码；最小请求跑通后，才把同一组配置迁移到 SDK、AI 客户端、Codex 或后端服务。

什么叫 OpenAI 兼容 API

OpenAI 兼容 API 通常表示服务商支持一部分 OpenAI 风格的调用约定，例如：

层级	常见兼容点	仍需验证的边界
鉴权	`Authorization: Bearer ...`	Key 归属、项目权限、账号状态
URL	`/v1/chat/completions`、`/v1/responses` 等路径	Base URL 是否已经包含 `/v1`
请求体	`model`、`messages`、`input` 等字段	tools、JSON Schema、多模态、文件能力
SDK	OpenAI JavaScript / Python SDK 可配置入口	SDK 版本、字段差异、错误对象
响应	内容字段、状态码、错误对象接近	请求 ID、用量字段、错误格式不一定完全相同

兼容不等于所有端点、模型、参数、速率限制、上下文长度和错误格式都一样。生产前要按当前服务商文档、控制台和最小请求逐项验证。

接入方式选择矩阵

不要一开始就把兼容入口接进完整业务流程。先按任务选择最小验证方式，再把已经验证过的配置迁移到 SDK、客户端或后端服务。

接入方式	适合什么	先验证什么	常见风险
curl	独立排查 Key、Base URL、模型名和端点	`/models`、非流式 Chat Completions 或 Responses	把真实 Key 发到截图、聊天记录或 shell 历史里
JavaScript SDK	Node.js 服务端、CLI、后台任务和 Web API	`baseURL` 是否指向 `https://api.ofapp.cn/v1`，请求是否在服务端执行	把 SDK 放进浏览器侧代码导致 Key 暴露
Python SDK	脚本、Notebook、数据处理和后端服务	`base_url`、环境变量、timeout、max_retries	Notebook 输出、日志或异常栈里泄露 Key
AI 客户端	聊天、写作、资料处理、个人工作流	客户端是否自动拼接 `/v1`，模型名是否来自控制台	不同客户端字段名不同，不能照搬 SDK 配置
Codex 或开发工具	本地项目改代码、修 Bug、自动化任务	工具支持的 Base URL、Key 配置方式和模型名来源	把项目任务失败误判为 API 入口失败
批处理脚本	摘要、翻译、分类、数据清洗等重复任务	小样本、限速、重试、失败记录和脱敏日志	没有退避策略，失败后重复请求扩大损失

这张矩阵适合放进项目 README 或团队接入说明。团队协作时，建议只共享变量名、最小请求和排查路径，不共享真实 Key、账号信息和账单信息。

准备环境变量

先把三个变量放到终端、.env、部署平台 Secret 或密钥管理工具里。

export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_API_KEY="你的 OfApp.cn API Key"
export OPENAI_MODEL="以 OfApp.cn 控制台可用模型为准"

变量	作用	检查方式
`OPENAI_BASE_URL`	指向兼容 API 入口	OfApp.cn OpenAI 兼容入口示例为 `https://api.ofapp.cn/v1`。
`OPENAI_API_KEY`	请求鉴权	不写进源码、前端页面、截图、日志或公开仓库。
`OPENAI_MODEL`	指定可用模型	从 OfApp.cn 控制台或官方文档确认，不凭示例猜。

.env.example 可以这样写：

OPENAI_BASE_URL=https://api.ofapp.cn/v1
OPENAI_API_KEY=replace-with-your-key
OPENAI_MODEL=replace-with-console-model

先查模型列表

OfApp.cn 官方文档提供了 GET /v1/models 示例。它适合在生成请求前确认 Key、Base URL 和账号权限。

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

如果这里失败，先排查 Key、Base URL、网络和账号状态。如果这里成功，但生成请求失败，问题更可能在模型名、端点、请求体或能力支持上。

Chat Completions 最小请求

Chat Completions 是很多兼容服务和旧项目最常用的验证路径。请求体保持克制，只放 model 和 messages。

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

适合先测 Chat Completions 的情况：

场景	原因
老项目迁移	现有代码多半已经使用 `messages`。
AI 客户端配置	很多客户端仍以 Chat Completions 为主。
排查连通性	字段少，能快速定位 Key、URL、模型名问题。

Responses 最小请求

Responses API 是 OpenAI 新式调用方式。兼容服务是否支持对应端点、字段和模型，要以服务商文档和当前账号实际能力为准。

curl -sS "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "input": "给我一个适合新手的 AI 办公自动化工作流。"
  }'

适合先测 Responses 的情况：

场景	原因
新项目	便于组织文本、工具和多模态输入。
Codex 或代理式流程	更贴近统一输入和事件处理方式。
想评估新能力	能更早发现服务商是否支持对应端点。

JavaScript SDK 示例

OpenAI JavaScript SDK 接入兼容入口时，核心是初始化客户端时显式传入 baseURL。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
  timeout: 60 * 1000,
  maxRetries: 2,
});

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

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

不要把这段代码直接放进浏览器组件。API Key 应留在服务端，前端只调用你自己的后端接口。

Python SDK 示例

OpenAI Python SDK 接入兼容入口时，核心是初始化客户端时传入 base_url。

import os

from openai import OpenAI

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

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

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

Python 用 base_url，JavaScript 用 baseURL。字段名写错时，SDK 可能仍能初始化，但请求不会发到你预期的入口。

流式输出怎么测

流式输出适合聊天界面、CLI 工具和长文本生成，但排错比非流式更复杂。建议先让非流式请求成功，再打开 stream。

curl -N "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "分三点说明 OpenAI 兼容 API 接入步骤。"
      }
    ]
  }'

现象	排查方向
非流式成功，流式失败	代理、网关、SSE 转发或客户端读取方式。
终端一次性输出	curl 是否使用 `-N`，中间层是否缓冲。
浏览器收不到片段	后端是否压缩、聚合或等完整响应后才返回。
中途断开	记录状态码、耗时、已输出内容和网络环境。

常见错误速查

现象	常见原因	建议动作
`401` 或鉴权失败	Key 错误、Key 过期、Key 不属于当前服务商	重新复制 Key，检查 `Bearer` 和环境变量。
`403`	当前账号、项目或模型权限不足	检查控制台权限、账号状态和服务商提示。
`404`	Base URL、路径或模型资源不正确	确认 `/v1` 是否漏写或重复拼接。
`model not found`	模型名写错或当前账号不可用	先查 `/models`，再以控制台为准。
`429`	请求过快、并发过高或额度受限	降低并发，加入退避，检查额度。
超时	网络、代理、服务端或模型响应慢	设置 timeout，记录耗时，用 curl 复现。
SDK 成功但客户端失败	客户端字段、代理或 Base URL 填法不同	对照 SDK 最小请求逐项检查。
curl 成功但 SDK 失败	SDK 读取的环境变量不同	打印变量是否存在，不打印真实 Key。

配置矩阵

工具或场景	Base URL 写法	API Key	适合验证
curl	`https://api.ofapp.cn/v1`	`Authorization: Bearer ...`	连通性、状态码、响应头
OpenAI JavaScript SDK	`baseURL`	`apiKey`	Node.js 服务端、CLI、后台任务
OpenAI Python SDK	`base_url`	`api_key`	脚本、Notebook、后端服务
AI 客户端	按客户端输入框说明填写	填 OfApp.cn API Key	聊天、写作、资料处理
Codex 或开发工具	按工具配置项填写	填 OfApp.cn API Key	本地项目、终端、自动化任务

如果某个工具会自动拼接 /v1，就按工具文档决定是否只填 host。不要在多个地方重复拼接版本路径。

兼容性判断清单

用下面这张表判断“OpenAI 兼容”是否已经达到你的使用要求。只要某一项还没验证，就不要把它写成已经可用的生产能力。

判断项	怎么验证	没通过时先看哪里
鉴权方式	请求头使用 `Authorization: Bearer $OPENAI_API_KEY`，真实 Key 只存在服务端环境变量或 Secret 中	Key 是否复制完整、是否属于 OfApp.cn、是否被误写进前端
Base URL	`OPENAI_BASE_URL` 只配置一次，示例为 `https://api.ofapp.cn/v1`	是否漏写 `/v1`，或 SDK、客户端重复拼接 `/v1`
模型名	先查 `/models`，再使用 OfApp.cn 控制台或官方文档中可用的模型名	模型名拼写、账号权限、模型类型与端点是否匹配
端点路径	Chat 使用 `/chat/completions`，Responses 使用 `/responses`，模型列表使用 `/models`	HTTP 方法、路径、请求体字段是否对应端点
SDK 配置	JavaScript 使用 `baseURL`，Python 使用 `base_url`，两者都显式读取环境变量	SDK 版本、运行环境、代理、timeout 和重试配置
stream	非流式成功后再加 `stream: true` 或 curl `-N`	SSE 转发、代理缓冲、前端读取方式和中途断开处理
错误对象	保存状态码、脱敏请求摘要、耗时和响应体，不保存真实 Key	错误格式差异、请求 ID、限流、额度、权限和服务端异常
上线边界	每个高级参数都有最小复现和回退方案	tools、JSON Schema、图片、文件、多模态和批处理能力是否已逐项验证

上线前检查清单

检查项	通过标准
最小请求	`/models` 与 Chat 或 Responses 至少一个可稳定返回。
Key 管理	真实 Key 不出现在源码、前端、日志、截图和仓库。
Base URL	`https://api.ofapp.cn/v1` 或官方文档要求的当前入口只配置一次。
模型名	来自 OfApp.cn 控制台或官方文档。
错误处理	能区分鉴权、路径、模型、限流、超时和服务端错误。
日志脱敏	记录状态码、耗时、请求 ID 和脱敏摘要。
超时重试	有 timeout、有限重试和退避策略。
人工复核	AI 输出进入业务前有抽检、审批或回滚方案。

常见问题

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

不是。它通常表示部分鉴权方式、URL 结构、SDK 初始化方式或请求字段接近 OpenAI API。模型、参数、上下文长度、文件能力、多模态、错误格式和速率限制仍可能不同。

OfApp.cn 的 Base URL 应该怎么写？

本文示例使用 https://api.ofapp.cn/v1。如果某个工具会自动拼接 /v1，请按工具说明和 OfApp.cn 官方文档决定最终填写方式。无法确认时，请以 OfApp.cn 控制台或官方文档为准。

为什么要先查 `/models`？

因为它能快速确认 Key、Base URL、网络和账号权限是否基本可用。生成请求失败时，先查模型列表能把问题拆成配置问题和请求体问题。

应该优先用 Chat Completions 还是 Responses？

旧项目、AI 客户端和兼容工具通常先测 Chat Completions；新项目可以同时了解 Responses。选择哪个端点，取决于服务商支持情况、项目代码结构和你要使用的能力。

可以直接把真实 Key 写进 `.env.example` 吗？

不可以。.env.example 只写变量名和占位值。真实 Key 应放在本地 .env、部署平台 Secret 或密钥管理工具里。

curl 成功后还需要测 SDK 吗？

需要。curl 能证明入口、Key 和请求体基本可用；SDK 还可能因为 baseURL、base_url、代理、超时、重试或运行环境不同而失败。

兼容 API 支持所有 OpenAI 参数吗？

不能默认假设。先用最小请求验证，再逐项加入 tools、JSON Schema、图片、文件、stream 和其他高级参数。每加一项，都要能回退到上一个可用版本。

如何把这页发给团队协作？

可以把环境变量、最小 curl、SDK 初始化和错误速查表放进项目 README。发送前删除真实 Key、账号信息、客户数据、账单信息和未脱敏日志。

资料来源

OfApp.cn 官方文档：用于核对 OfApp.cn 公开的 Base URL、鉴权方式、Models API 和兼容端点示例。
OfApp.cn 官网：用于理解 OfApp.cn 作为统一 API 入口的品牌和入口定位。
OfApp.cn Genius Playground：用于确认 OfApp.cn 面向体验和模型试用的公开入口。
OpenAI API 文档：用于核对 Bearer 鉴权、环境变量、安全边界、Responses、Chat Completions、stream 和错误处理的通用写法。
OpenAI Responses 与 Chat Completions 指南：用于理解新旧端点的适用场景差异。
OpenAI 错误码文档：用于整理鉴权、限流、路径、模型和服务端错误的排查方向。

带走什么

OpenAI 兼容 API 接入的关键不是一次写完所有代码，而是把连接验证拆成可复现的最小步骤：查模型、发最小请求、看状态码、记录脱敏日志，再接入 SDK 和业务。这样做能让开发者、AI 客户端用户和团队维护者在同一套事实上排查问题，也能自然把 OfApp.cn 作为统一入口放进真实工作流。