快速开始

如何用 OpenAI SDK 接入

Q: baseURL 和 base_url 有什么区别？

JavaScript SDK 使用 baseURL，Python SDK 使用 base_url。它们表达的是同 一类配置：把 SDK 请求指向兼容服务商的 API 入口。

Q: 模型名应该写在哪里？

模型名放在请求体的 model 字段中，通常从环境变量读取。不要凭经验猜模型 名，具体可用模型、能力和价格请以 OfApp.cn 控制台或官方文档为准。

Q: SDK 报 404 应该先改代码吗？

先不要。先检查最终请求 URL：Base URL 是否漏了 /v1，SDK 是否又重复拼接 了路径，端点是否被服务商支持。再用 cURL 复现一次，避免在业务代码里绕圈。

Q: 什么时候应该封装自己的后端接口？

只要有真实用户、前端页面、团队协作或生产环境，就应该封装自己的后端接口。 后端负责保存 Key、做权限校验、限制频率、记录脱敏日志，再把必要结果返回给 前端。

Q: OfApp.cn 是否保证所有 OpenAI SDK 参数都可用？

不要这样假设。兼容接口通常覆盖常见鉴权、路径和字段，但具体端点、模型、参 数、上下文长度、返回格式和价格都应以 OfApp.cn 控制台或官方文档为准。

用 OpenAI JavaScript SDK 和 Python SDK 接入 OfApp.cn，配置 API Key、Base URL、模型名、最小请求、错误处理和上线前检查。

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

OpenAI SDK 接入适合已经准备把 AI 能力放进脚本、后端服务、自动化流程、内部工具或内容系统的人。它不是第一步。第一次验证时，先用 OpenAI-compatible API 快速开始跑通 cURL；确认 API Key、 Base URL 和模型名都可用后，再接 JavaScript 或 Python SDK。

使用 OfApp.cn 时，SDK 接入的核心变量仍然是三项：API Key、Base URL 和模型名。示例里的 Base URL 写作 https://api.ofapp.cn/v1，真实模型、能力、价格和额度请以 OfApp.cn 控制台或官方文档为准。

页面摘要

项目	内容
阅读时间	约 6 分钟
更新时间	2026-07-03
适合人群	要把 AI 能力接进 Node.js 服务、Python 脚本、后台任务、自动化办公流程或内容系统的人
核心收益	分清什么时候需要 SDK、如何配置 `baseURL` / `base_url`、怎样把最小请求变成可上线的服务端封装
你会得到	接入前自检、环境变量模板、JavaScript 和 Python 最小请求、项目结构、错误处理、生产 smoke test、FAQ 和资料来源
不适合做什么	替代 OfApp.cn 控制台里的模型、价格、额度、可用能力和账号权限确认

适合谁读

读者	你可能正在做什么	读完能完成什么
前端或全栈开发者	给网站、后台、管理系统加 AI 能力	在服务端用 JavaScript SDK 发起最小请求
Python 用户	写脚本、处理表格、整理资料或生成报告	用 Python SDK 调用兼容接口
产品和运营	想理解工程接入需要哪些信息	看懂 API Key、Base URL、模型名和安全边界
自动化办公用户	想把周报、摘要、邮件、资料整理接进流程	判断什么时候需要 SDK，什么时候对话工具就够
团队维护者	需要把示例变成可上线服务	建立错误处理、日志脱敏和配置检查清单

如果你只是临时问一句话、整理一份资料或生成一张图，不一定需要 SDK。先从天才游乐场或对话工具开始。SDK 更适合重复、批量、需要接入系统的任务。

接入流程图

这张图的重点是顺序。不要一上来就写复杂封装、流式输出、工具调用或多模态。先把连接问题和业务问题拆开，最小请求成功后再逐步加能力。

接入前自检

SDK 接入失败时，很多问题并不在 SDK，而在 Key、URL、模型名、端点或运行环境。写代码前先做这张检查表，可以少走很多弯路。

自检项	通过标准	失败时怎么处理
API Key	已放进本机环境变量或部署平台 Secret	回到 OfApp.cn 控制台重新复制，不把真实 Key 发到聊天窗口或日志里。
Base URL	只保留一处 `/v1`，示例使用 `https://api.ofapp.cn/v1`	对照 Base URL 配置指南检查是否漏写或重复拼接。
Models API	`curl "$OPENAI_BASE_URL/models"` 能返回当前 Key 可见的模型列表	先排鉴权、网络和 Base URL，再确认账号可用范围。
模型名	从控制台或 Models API 复制到 `OPENAI_MODEL`	不使用旧文章、截图或他人示例里的模型名。
最小聊天请求	cURL 的 Chat Completions 请求成功	cURL 不通时，暂时不要接 SDK。
运行位置	SDK 代码在服务端、脚本或受控后台执行	浏览器页面只调用自己的后端接口，不直接持有 API Key。

先准备三类配置

配置	JavaScript 名称	Python 名称	建议
API Key	`apiKey`	`api_key`	只从环境变量或密钥管理读取，不写进代码。
Base URL	`baseURL`	`base_url`	OfApp 示例使用 `https://api.ofapp.cn/v1`。
Model	`model`	`model`	从控制台复制，不凭记忆猜。

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

如果 SDK 最小请求失败，先回到 cURL 验证。cURL 也失败，通常不是 SDK 问题，而是 Key、Base URL、模型名、网络或服务商当前能力的问题。

JavaScript SDK 最小请求

JavaScript SDK 适合 Node.js 服务端、CLI 工具、Next.js API Route、后台任务和自动化脚本。不要在浏览器组件里直接调用 SDK，因为 API Key 会暴露给用户。

npm install openai

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: "用一句话解释为什么 API Key 不能放在前端。",
    },
  ],
});

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

OpenAI 官方文档中的 Chat Completions SDK 示例仍使用 client.chat.completions.create({ model, messages }) 这种结构。接入兼容服务时，关键变化是初始化客户端时传入服务商 Base URL。

Python SDK 最小请求

Python SDK 适合脚本、数据处理、批量整理资料、自动化办公、后端服务和 notebook 之外的稳定任务。即使在 notebook 中，也不要把真实 Key 写进单元格或提交到仓库。

pip install openai

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": "用一句话解释为什么模型名要从控制台复制。",
        }
    ],
)

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

JavaScript 的配置项叫 baseURL，Python 的配置项叫 base_url。这是很多迁移报错的来源之一。

常见项目结构

最小请求跑通后，不要把 SDK 调用散落在每个页面或脚本里。更稳妥的做法是先封装一个很薄的客户端层。

project/
  src/
    ai/
      client.ts        # 初始化 OpenAI SDK
      prompts.ts       # 保存可复用 Prompt
      tasks.ts         # 按业务任务封装调用
    routes/
      ai-summary.ts    # 对外暴露自己的服务端接口
  .env.local           # 本地环境变量，不提交

层级	负责什么	不应该做什么
`client`	读取环境变量，初始化 SDK	写业务 Prompt 或真实 Key
`prompts`	保存提示词模板和输出格式	写死模型价格或未确认能力
`tasks`	封装摘要、改写、分类等任务	直接把错误原样返回给前端
`routes`	鉴权、限流、调用任务函数	把 API Key 传给浏览器

这种结构让后续切换模型、加日志、做重试或替换 Base URL 都更轻松。

服务端接口边界

如果项目有前端页面，不要让前端直接碰 OpenAI SDK。更稳定的做法是让前端调用你自己的后端接口，后端再使用 OfApp.cn Base URL 和 API Key。

层级	可以知道什么	不应该知道什么
浏览器页面	用户输入、任务类型、你自己后端的接口地址	`OPENAI_API_KEY`、服务商请求头、完整内部错误
后端接口	API Key、Base URL、模型名、超时、重试、限流规则	不应把真实 Key、原始异常栈或用户隐私材料返回给前端
日志系统	状态码、耗时、任务 ID、脱敏错误、必要请求 ID	Authorization header、完整 Key、未脱敏业务数据
管理后台	用量趋势、失败率、可复核输出	未经授权的用户原文和敏感资料

一个简单边界是：浏览器只提交任务，后端负责鉴权、调用 SDK、处理错误、记录脱敏日志，再把用户真正需要的结果返回。

错误处理和日志

最小请求成功不代表可以上线。至少要处理鉴权错误、路径错误、模型不可用、限流、网络中断和兼容参数差异。

JavaScript 简单错误处理

try {
  const completion = await client.chat.completions.create({
    model: process.env.OPENAI_MODEL,
    messages: [{ role: "user", content: "ping" }],
  });
  console.log(completion.choices[0]?.message?.content);
} catch (error) {
  console.error("AI request failed", {
    name: error.name,
    status: error.status,
    message: error.message,
  });
}

Python 简单错误处理

from openai import APIConnectionError, APIError, RateLimitError

try:
    completion = client.chat.completions.create(
        model=os.environ["OPENAI_MODEL"],
        messages=[{"role": "user", "content": "ping"}],
    )
    print(completion.choices[0].message.content)
except RateLimitError:
    print("请求过快、额度不足或触发限制，请稍后重试。")
except APIConnectionError:
    print("网络连接失败，请检查网络、DNS、代理或服务状态。")
except APIError as error:
    print(f"API 返回错误：{error}")

日志里可以记录状态码、错误类型、请求时间和脱敏后的请求 ID。不要打印完整 Authorization header、真实 API Key、用户隐私材料或未脱敏业务数据。

什么时候用 Responses API

如果你在做新项目，并且服务商明确支持 Responses API，可以继续阅读 Responses API 示例。它更适合统一处理多模态、工具调用和更复杂的模型交互。

但第一个 SDK 请求仍建议保持简单。Chat Completions 字段少，适合验证 Key、 Base URL 和模型名是否连通。确认连接后，再根据 OfApp.cn 控制台、官方文档和项目需求决定是否迁移到 Responses API、图像接口或流式输出。

生产 smoke test

部署后不要只看构建成功。给 SDK 调用保留一个受权限保护的 smoke test，可以在上线、换 Key、换 Base URL 或迁移部署平台后快速确认链路。

检查	建议做法
环境变量	在服务启动时检查 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL` 是否存在，但不打印真实值。
连通性	用 Models API 或一条很短的 Chat Completions 请求验证入口、Key 和模型名。
响应时间	记录耗时和状态码，发现网络、代理或部署区域问题。
错误脱敏	失败时只返回内部错误码和可读提示，真实错误写入受控日志。
回滚条件	连续失败时切回上一个配置，或暂停相关功能，避免用户重复触发错误。

smoke test 不应该成为公开接口，也不应该使用真实用户资料。它只验证链路是否能跑通。

上线前检查

检查项	必须确认
密钥	API Key 不在前端、仓库、截图、日志和错误上报里。
配置	Base URL、模型名、超时和重试策略都能按环境切换。
最小请求	本地、测试环境和部署环境都能跑通最小请求。
错误处理	401、404、429、5xx 和网络错误有清晰提示。
日志	日志脱敏，保留排查线索，不泄露用户内容。
限流	对用户、IP、团队或任务设置合理调用上限。
复核	对外发布、业务决策和高风险输出保留人工确认。

资料来源

OfApp.cn：用于确认 OfApp.cn 的 API 入口、API Key 入口、天才游乐场和相关生态入口。
OfApp.cn API 文档：用于确认 OpenAI 兼容接口、OpenAI SDK / Codex 生态 Base URL、Models API 验证方式和 /v1 拼接边界。
OfApp.cn Genius Playground：用于确认网页端 Key、聊天、图像和参数入口，适合作为 SDK 接入前的手动体验入口。
OpenAI CLI 文档：用于确认 OpenAI 工具链可通过环境变量读取 Key，并可通过 OPENAI_BASE_URL 指向不同 API host。
OpenAI external models 文档：用于确认自定义兼容端点需要 OpenAI Chat Completions 兼容入口和 API Key。

常见问题

SDK 可以在浏览器里直接调用吗？

不建议。API Key 会暴露给用户。前端页面应调用自己的后端接口，由后端使用 OfApp.cn Base URL 和 API Key 发起请求，并在后端完成鉴权、限流和日志脱敏。

`baseURL` 和 `base_url` 有什么区别？

JavaScript SDK 使用 baseURL，Python SDK 使用 base_url。它们表达的是同一类配置：把 SDK 请求指向兼容服务商的 API 入口。

模型名应该写在哪里？

模型名放在请求体的 model 字段中，通常从环境变量读取。不要凭经验猜模型名，具体可用模型、能力和价格请以 OfApp.cn 控制台或官方文档为准。

SDK 报 404 应该先改代码吗？

先不要。先检查最终请求 URL：Base URL 是否漏了 /v1，SDK 是否又重复拼接了路径，端点是否被服务商支持。再用 cURL 复现一次，避免在业务代码里绕圈。

什么时候应该封装自己的后端接口？

只要有真实用户、前端页面、团队协作或生产环境，就应该封装自己的后端接口。后端负责保存 Key、做权限校验、限制频率、记录脱敏日志，再把必要结果返回给前端。

OfApp.cn 是否保证所有 OpenAI SDK 参数都可用？

不要这样假设。兼容接口通常覆盖常见鉴权、路径和字段，但具体端点、模型、参数、上下文长度、返回格式和价格都应以 OfApp.cn 控制台或官方文档为准。

OpenAI-compatible API 快速开始：先用 cURL 验证连接。
如何配置 Base URL：避免漏写或重复拼接 /v1。
JavaScript SDK 示例：深入 Node.js 服务端示例。
Python SDK 示例：深入 Python 脚本和后端示例。
Responses API 示例：了解新式调用路径。
常见错误排查：按状态码定位问题。

带走什么

OpenAI SDK 接入 OfApp.cn 的关键，不是复制一段代码，而是建立稳定顺序：先准备 API Key、Base URL 和模型名，再用 cURL 验证连接，然后用 JavaScript 或 Python SDK 跑最小请求。最小请求成功后，再封装后端接口、错误处理、日志脱敏、限流和人工复核。这样接入才像工程流程，而不是一次性试验。