OpenAI Compatible API curl 调用示例

一句话回答

OpenAI Compatible API 可以用 curl 直接调用。最稳的顺序是：先请求 /models 验证 Base URL 和 API Key，再请求聊天接口生成内容。这样能快速判断问题出在认证、地址、模型名还是请求体。

如果你的 Base URL 是 https://api.tokencheap.space/v1，模型列表请求通常是：

curl "https://api.tokencheap.space/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

准备工作

你需要准备三样东西：

API Base URL，例如 https://api.tokencheap.space/v1
API Key，例如服务商后台生成的 Key
模型名，例如服务商模型列表中返回的模型 ID

如果不确定 Base URL 和 Key 的区别，先看 API Base URL 是什么？和 API Key 有什么区别？。

第一步：用 /models 验证连接

先不要直接发复杂聊天请求。先查模型列表：

curl "https://api.tokencheap.space/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

如果返回模型列表，说明：

API 地址可访问。
API Key 基本有效。
后续模型名应该从列表中选择。

如果返回 401，优先看 OpenAI API 401 Unauthorized 怎么解决。如果返回 timeout，优先看 API timeout 超时解决方法。

第二步：发送聊天请求

OpenAI-compatible 服务通常会兼容聊天接口。示例：

curl "https://api.tokencheap.space/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "用一句话解释 API Base URL 是什么"}
    ]
  }'

注意：模型名要使用服务商支持的模型 ID。如果模型名不存在，会出现 model_not_found。

Windows PowerShell 写法

PowerShell 对引号比较敏感，可以先把 JSON 放进变量：

$body = @{
  model = "gpt-4o-mini"
  messages = @(@{ role = "user"; content = "你好" })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "https://api.tokencheap.space/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer YOUR_API_KEY" } `
  -ContentType "application/json" `
  -Body $body

如果你只是测试连接，curl 更直接；如果要接入自动化脚本，PowerShell 或 Python 更方便。

常见错误排查

401 Unauthorized

说明认证失败。检查 Key 是否完整、是否带 Bearer、是否和 Base URL 属于同一个服务商。

404 Not Found

通常是 URL 路径错了。确认 Base URL 是否带 /v1，endpoint 是否拼成 /chat/completions。

model_not_found

模型名不在当前服务支持列表里。先请求 /models，再复制模型 ID。

429 Too Many Requests

请求太频繁或额度问题。参考 OpenAI API 429 Too Many Requests 怎么解决。

timeout

网络无法访问 API 域名。自部署服务器要在服务器上执行 curl，而不是只在本地电脑测试。

curl 测试适合哪些场景

Cursor 配置失败前，先验证 Key 是否可用。
Dify 供应商测试失败时，排除网络和认证问题。
n8n Credential 不工作时，验证服务器访问能力。
自己写代码前，确认服务商接口兼容程度。

FAQ

curl 调用 OpenAI Compatible API 最小命令是什么？

最小验证命令是请求 /models，带上 Authorization: Bearer YOUR_API_KEY。

curl 里 Base URL 要写到哪里？

完整 URL 通常是 Base URL + endpoint，例如 https://api.tokencheap.space/v1/models。

为什么聊天接口返回 model_not_found？

模型名不在当前 Base URL 支持列表中。先请求 /models 获取可用模型名。

可以直接复制 OpenAI 官方 curl 示例吗？

可以借用结构，但要把 Base URL、API Key 和模型名换成当前服务商提供的值。

curl 成功但 Cursor/Dify/n8n 失败怎么办？

说明 API 服务本身可用，下一步检查工具里的 Base URL、模型名、Credential 引用和运行环境网络。