curl 示例

curl 是排查 OpenAI-compatible API 的第一把小刀。它不依赖 SDK、不依赖编辑器、不依赖框架，只要网络、Base URL、API Key 和请求体正确，就能直接看到接口是否连通。

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

先用 curl 跑通统一 API 入口

当 SDK、AI 编程工具或自动化脚本出现异常时，curl 能帮助你把问题拆回网络、鉴权、模型名和请求格式。

查看 OfApp.cn 接入说明

页面摘要

项目	内容
适合人群	想独立验证 OfApp.cn API Key、Base URL、模型名和请求体的开发者、运营、研究者和 AI 初学者
阅读时间	约 6 分钟
核心问题	如何用 curl 把 SDK、框架和业务代码之外的 API 连通性单独验证出来
你会得到	环境变量模板、配置自检、Models API、Chat Completions、Responses、stream、响应头、状态码和脱敏日志模板
安全边界	真实 API Key、账号信息、客户内容和账单信息不要写进命令截图、仓库、聊天记录或公开日志

适合谁读

读者	典型场景	curl 能帮你确认什么
开发者	SDK 调用失败、服务端报错、部署后环境变量不生效	Base URL、鉴权、请求体、状态码
产品经理	想快速验证某个 AI 功能是否可行	最小请求能否拿到结果
运营和内容团队	想测试提示词、批量生成摘要或翻译	请求格式、模型响应、流式输出
老师、学生、科研人员	想在脚本或命令行里调用 AI	Key 是否可用、模型是否可访问
AI 初学者	不确定问题出在平台、工具还是代码	先把接口连通性独立验证

curl 排错流程图

前置条件

准备两个环境变量。这样命令可以复用，也能减少把 Key 写进聊天记录、截图或仓库的风险。

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

如果你要把命令发给同事、客服或 AI 助手，请把 OPENAI_API_KEY、账号邮箱、项目名、账单信息和完整响应里的敏感字段先删掉。

环境变量自检

先确认终端真的读到了变量，但不要打印真实 Key。

printf "base url: %s\n" "$OPENAI_BASE_URL"
printf "key set: %s\n" "$([ -n "$OPENAI_API_KEY" ] && echo yes || echo no)"
printf "model set: %s\n" "$([ -n "$OPENAI_MODEL" ] && echo yes || echo no)"

如果你怀疑 Base URL 拼接错误，可以只检查末尾是否为 /v1。

case "${OPENAI_BASE_URL%/}" in
  */v1) echo "base url has /v1" ;;
  *) echo "base url may miss /v1" ;;
esac

查询模型列表

先查模型列表，比直接发送生成请求更稳。它可以快速确认 Base URL、网络和鉴权是否正常。

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

如果这里失败，先不要改业务代码。优先检查：

• OPENAI_BASE_URL 是否包含 /v1。
• Authorization 是否使用 Bearer。
• API Key 前后是否混入空格、引号或换行。
• 当前网络是否能访问 https://api.ofapp.cn。
• 控制台中该 Key 是否仍然有效。

curl 命令选择矩阵

不同命令解决的问题不一样。先选对验证目标，能少走很多弯路。

目标	推荐命令	看什么结果	失败后先查什么
验证入口和鉴权	GET /models	能返回模型列表或可解释错误	Base URL、Bearer、Key 是否有效
验证旧项目兼容	POST /chat/completions	有生成内容、错误对象或状态码	messages 格式、模型名、JSON 引号
了解新接口形态	POST /responses	有 output_text 或兼容服务返回字段	端点是否支持、模型是否支持
排查网关和状态码	curl -i 或 curl -w	HTTP 状态码、耗时、响应头	网络、代理、限流、服务端错误
验证流式输出	curl -N + stream: true	终端能逐段输出	终端缓冲、代理缓冲、SSE 链路
复现复杂请求	-d @payload.json	命令行引号不再干扰 JSON	payload 是否含真实 Key 或敏感内容

Chat Completions 最小请求

如果你的工具、旧项目或教程使用 chat/completions，可以先用下面的最小请求验证。

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-compatible API。"
      }
    ]
  }'

返回结果里通常要重点看三类信息：是否有生成内容、是否有错误对象、是否包含可用于排查的请求标识或状态信息。具体字段请以 OfApp.cn 官方文档和接口实际返回为准。

Responses 最小请求

新项目可以同时了解 responses 写法。它的请求体更直接，适合把输入、工具调用和多模态能力放进统一接口里组织。

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

如果你正在迁移旧代码，可以把 Chat Completions 与 Responses 分开测试：先确认旧接口可用，再评估是否要改成新的请求结构。

查看响应头和状态码

生成内容不是排错时的唯一信息。状态码、响应头和原始错误体往往更有价值。

curl -i "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "ping"
      }
    ]
  }'

如果你只想保存响应体，同时在终端打印状态码，可以这样写：

curl -sS -o /tmp/ofapp-response.json \
  -w "http_code=%{http_code}\ntime_total=%{time_total}\n" \
  "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "ping"
      }
    ]
  }'

流式请求

流式输出适合聊天、写作助手、代码助手和需要边生成边显示的界面。curl 里要使用 -N 关闭缓冲，避免终端等到整段完成才显示。

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": "分三步说明如何用 AI 整理会议纪要。"
      }
    ]
  }'

如果终端没有逐段显示，先确认命令里有 -N，再检查代理、网关、反向代理或运行环境是否对流式响应做了缓冲。

Windows PowerShell 写法

PowerShell 里 curl 可能是别名。为了避免参数行为不同，建议直接使用 curl.exe。

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

@'
{
  "model": "$env:OPENAI_MODEL",
  "messages": [
    {
      "role": "user",
      "content": "用一句话解释 API Key 为什么要保密。"
    }
  ]
}
'@ | curl.exe "$env:OPENAI_BASE_URL/chat/completions" `
  -H "Authorization: Bearer $env:OPENAI_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@-"

注意：单引号 here-string 不会展开 $env:OPENAI_MODEL。如果你希望 PowerShell 自动替换变量，可以改用双引号 here-string，或者把模型名直接写入 JSON。写入前仍需以 OfApp.cn 控制台或官方文档为准。

常见现象速查

现象	常见原因	建议动作
401 或鉴权失败	Key 错误、Key 过期、Bearer 写法不对	重新复制 Key，检查是否多了空格或换行
404	Base URL 或路径错误	确认 https://api.ofapp.cn/v1 与接口路径是否拼接正确
模型不可用	模型名写错，或当前账号不可用	先调用 /models，再以控制台为准
429	请求过快或额度受限	降低并发，检查额度、速率限制和控制台提示
超时	网络、代理、服务器或模型响应慢	用 -w 打印耗时，分开测试网络与请求体
stream 不连续	终端、代理或网关缓冲	使用 -N，检查中间层是否支持流式响应
Shell 报引号错误	JSON 与命令行引号冲突	把 JSON 存成文件，使用 -d @payload.json
curl 成功但 SDK 失败	SDK 配置、环境变量名或运行时不同	对比 SDK 的 Base URL、Key、模型名和代理配置

JSON 文件写法

复杂请求建议把 JSON 放进文件，减少引号问题。

{
  "model": "以 OfApp.cn 控制台可用模型为准",
  "messages": [
    {
      "role": "user",
      "content": "帮我把这段会议记录整理成行动项。"
    }
  ]
}

保存为 payload.json 后再发送：

curl -sS "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

这种方式更适合团队协作，也更适合把请求样例放进测试脚本。提交到仓库前请确认文件里没有真实 Key、内部客户数据或未脱敏内容。

脱敏日志模板

排查问题时，可以把下面的模板发给同事或支持人员。它保留了关键线索，又避免泄露敏感信息。

时间：
环境：本地 / 服务器 / CI
Base URL：https://api.ofapp.cn/v1
接口路径：/chat/completions 或 /responses
HTTP 状态码：
请求是否使用 stream：
模型名：已脱敏或以控制台为准
错误摘要：
curl -w 输出的 time_total：
已确认：API Key 未贴出、请求体敏感内容已删除

最小排查清单

把问题交给 SDK 或框架前，建议先确认这 6 件事：

检查项	通过标准
Base URL	使用 https://api.ofapp.cn/v1
API Key	环境变量可读取，且没有多余空白
模型名	来自 OfApp.cn 控制台或官方文档
鉴权头	Authorization: Bearer ...
请求体	JSON 结构合法，字段名没有拼写错误
响应信息	记录状态码、错误体和请求耗时

常见问题

curl 成功但 SDK 失败说明什么？

通常说明平台入口、网络和 Key 已经基本可用，问题更可能在 SDK 配置、环境变量名、代理、运行目录或模型名读取逻辑。把 curl 使用的 Base URL、Key 来源和模型名逐项对照 SDK 配置。

curl 失败但浏览器能打开域名怎么办？

浏览器能打开首页，只能说明域名可访问。API 请求还需要正确路径、鉴权头、请求方法和 JSON 请求体。用 /models 先验证鉴权，再测试生成接口。

Base URL 一定要带 /v1 吗？

本文示例使用 https://api.ofapp.cn/v1。很多 OpenAI-compatible SDK 会把接口路径拼在 Base URL 后面，漏掉 /v1 可能导致路径错误。具体仍以 OfApp.cn 官方文档为准。

应该先测 Responses 还是 Chat Completions？

如果你在排查旧项目或兼容工具，先测 Chat Completions 更贴近现场。如果你在做新项目，可以同时测试 Responses，便于后续接入更统一的输入结构。

如何确认模型名可用？

先调用 /models，再到 OfApp.cn 控制台确认当前账号可用的模型、权限和额度。不要只凭网上示例里的模型名判断。

为什么要看响应头和状态码？

因为很多错误不会体现在生成内容里。状态码能快速区分鉴权、路径、限流、请求体和服务端问题；响应头与耗时能帮助判断网络链路和中间层行为。

流式请求没有逐字输出怎么办？

先确认 curl 使用了 -N，再检查终端、代理、网关、反向代理和部署平台是否缓冲响应。可以先在本机命令行测试，再放回浏览器或服务端代码里验证。

可以把 curl 命令发给同事或 AI 吗？

可以，但要先脱敏。删除真实 API Key、账号信息、客户内容、内部文件名、账单信息和完整原始响应里的敏感字段，只保留状态码、路径、脱敏后的模型名和错误摘要。

相关文章

• OpenAI Compatible API 实战
• OpenAI 兼容 API 快速开始
• Base URL 配置指南
• 故障排查指南
• Chat Completions 示例
• 流式输出示例
• JavaScript SDK 示例
• Python SDK 示例
• API 错误排查中心

资料来源

• OfApp.cn 官方文档：核对 API Key、Base URL、Bearer 鉴权、/v1 入口和 curl 示例相关信息。
• OfApp.cn 官网：核对 OfApp.cn 面向 OpenAI、Codex、GPT Image、Claude 和 AI 客户端的入口语境。
• 天才游乐场：核对普通用户从网页入口体验模型、图片和 Key 配置的上下文。
• OpenAI API 文档：参考 API Key、Bearer 认证、Responses、Chat Completions 和 curl 请求形态。
• OpenAI Responses 与 Chat Completions 指南：参考两类端点的定位差异；OfApp.cn 实际支持情况请以控制台或官方文档为准。

带走什么

curl 的价值不在于替代 SDK，而在于把复杂问题拆回最小闭环：入口是否正确、Key 是否有效、模型是否可用、请求体是否合规、响应是否可解释。只要这个闭环稳定，后续接入网站、自动化脚本、AI 编程工具或办公工作流都会更稳。