curl 测试 OpenAI 兼容 API 的完整流程

你照着文档发了一个 curl 请求，结果不是 404 就是 401，偶尔还提示 model 不存在。先别急着换 SDK。问题通常不在模型，而在请求地址少了一段路径、认证头没带对、model 名填了上游原名。这篇文章用一条 curl 命令把 openai 兼容 api 测试流程跑通，从环境变量设置到最小示例，再到流式请求和排错，完成后你能在终端里稳定复现一次合法响应。

场景与前置条件

这个流程适合你已经有一个可用的 key 和一个模型调用名，但不确定端点路径、请求头或返回格式。目标是在终端里用 curl 完成一次 openai 兼容 api 的 chat 补全调用，不依赖 Python SDK。只要服务方声明兼容 OpenAI 的 /chat/completions，这个步骤就能套用；只是 base_url 和 model 名要换成平台文档里的值。

先确认你的环境里有 curl。Linux 和 macOS 通常自带，Windows 10 1803 以后也随系统带了 curl.exe。命令里如果用了单引号，Windows CMD 会处理不了，需要切到 PowerShell、Git Bash 或 WSL。jq 不是必需，但对格式化 JSON 很有用，后面会顺手用一下。

环境准备

打开一个终端，把密钥放进当前 shell 的环境变量。密钥设置成环境变量后，curl 命令通过 $ 后面的变量引用它，不会把 sk_live_ 前缀的值写进脚本。不要硬编码在命令历史或 Git 仓库里，这是最简单的防泄漏方式。当前 shell 关闭后这个变量会消失，CI/CD 里要放到 secret 管理。

接着确认终端可以访问外网。由于这个 openai 兼容 api 的请求是 HTTPS JSON，不需要额外安装证书。可以直接执行最小示例更快。想省事可以另开一个终端窗口专门保存环境变量，免得每次重开都 export。

最小可跑示例

下面这条命令包含三个决定成败的要素：完整路径、认证头、JSON body。路径的前缀和 /chat/completions 后缀都不能省，少一段常见表现就是 404。

bash 复制代码

curl https://www.silvamux.com/api/v1/chat/completions -H "Authorization: Bearer $SILVAMUX_API_KEY" -H "Content-Type: application/json" -d '{"model":"deepseek-v3.2","messages":[{"role":"user","content":"用一句话解释 HTTPS"}],"max_tokens":64,"stream":false}'

这条命令会向 /chat/completions 发一个非流式请求。Authorization 头必须是 Bearer 加环境变量里的 key；如果 key 没导出，认证头引用会变成空字符串，网关会返回 401，而不是参数错误。Content-Type 必须为 application/json，有些网关收到表单类型会直接 400。model 填的是平台调用名 deepseek-v3.2，不是上游原始命名。这里 max_tokens 设成 64，只为了快速看到完整 JSON；stream 为 false 时响应是一个普通 JSON 块，适合先确认连通性。

如果响应里出现 choices[0].message.content，说明地址、认证、模型名都对了。这个字段就是模型返回的文本。没有 jq 的情况下可以先看原始 JSON；有 jq 可以把输出管道给 jq '.choices[0].message.content'。

逐步扩展

连通之后，第一个实用改动是看 HTTP 状态码和响应头。排错时只看 body 会被网关拦截，X-Request-Id 能帮你定位具体请求。-w 用来输出状态码，-D 把响应头写进文件，组合起来不影响主流程。

第二个实用能力是改用 Python SDK 写一个最小脚本。原因不是 curl 不够用，而是当你要调试重试、超时、流式回调时，SDK 的循环比 shell 好处理。先 pip install openai，然后保存下面的 Python 文件。

python 复制代码

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SILVAMUX_API_KEY"],
    base_url="https://www.silvamux.com/api/v1",
)

resp = client.chat.completions.create(
    model="deepseek-v3.2",
    messages=[{"role": "user", "content": "用一句话说明 HTTPS"}],
    max_tokens=64,
)
print(resp.choices[0].message.content)

这段代码做的事和 curl 版本完全一样，只是把接口细节收进了 OpenAI 类的构造参数。注意 base_url 必须写成完整的 /api/v1，不能只写域名；api_key 从环境变量读取，仍然不落盘。model 继续用 deepseek-v3.2。如果你把 model 换成模型广场里另一个别名，脚本其他位置不用动。

两个扩展的差别很直接：curl 版本适合一次性探活，SDK 版本适合后续加流式、重试和异常分支。-D 选项只在 shell 里管用，抓响应头要用 -i 或 -D；SDK 的响应对象已经带 headers 属性，但用法各语言有差异。

排错

404 Not Found

报错文本通常是一段 HTML 或 {"detail":"Not Found"}，取决于网关。直接原因几乎都是路径不对：/api/v1 没了，或者把域名写成了 api 开头。修法是回到最小示例，把请求地址的前缀补成 /api/v1，后缀保持 /chat/completions。可以先 echo 出完整 URL 肉眼检查，再发请求。

401 Unauthorized

报错文本里常见 Invalid API key 或 401 Unauthorized。直接原因是认证头里的 key 为空或错误。最容易踩的是当前 shell 没 export，或者窗口重开导致变量没了。修法：先 echo 一下 key 的长度，不要打印完整值；再确认请求头写成 Authorization: Bearer $ 加环境变量名。如果 key 确实无效，去控制台查状态。

model 不存在

报错文本可能是 model does not exist 或 gateway_error 里的错误码。直接原因是 model 名用了上游厂商原名或自己拼的版本号。修法是去模型广场详情页复制稳定 alias，不要用展示名拼接。示例里的调用名就别改成 deepseek-chat。

如果遇到 429 或 5xx，不要改参数。429 按指数退避重试，500/502 间隔 1-5 秒再试。每次请求看 X-Request-Id 头，排错时带上这个值，能少绕很多路。

常见问题

问：为什么拿 curl 能通，Python 脚本却 404？

大概率是 base_url 少了 /api/v1，因为 SDK 的 base_url 会直接拼接 /chat/completions。curl 里能写完整路径，SDK 构造时容易只写到域名。对照最小示例的构造参数改回完整前缀即可。

问：流式请求会多一个空 choices 片段，算不算 bug？

不算。openai 兼容 api 的流式响应末尾可能只带 usage，choices 为空。处理 SSE 时不要只等 data: [DONE]，要把流正常结束也当作结束条件，否则容易卡住。

问：测试时想保护 key，应该怎么做？

永远用环境变量，别把 key 写进脚本或截图。shell history 可以在测试后清理；如果公开录屏，先吊销再生成新 key。请求头里的 Authorization 也只能在 HTTPS 里传输。

以上示例在千木SilvaMux的 OpenAI 兼容端点上验证，模型调用名为 deepseek-v3.2。接口参数更新见开发者文档。