curl 调用大模型 API 教程：请求示例与 401、404、429 排查

用 curl 调用大模型 API，可以直接查看 HTTP 状态码和响应正文，帮助区分请求参数、鉴权与接口路径问题。本文从一条最小 Chat Completions 请求开始，再解释返回结果及 401、404、429 的排查顺序。

本文使用 macOS / Linux 的 Bash 终端，调用 TokenDance 的 OpenAI Chat Completions 接口。Windows 用户可以在 WSL 中跟做，或使用 Python 版本。

1. 准备三个信息

在 API 密钥页创建密钥，然后从模型列表复制支持 OpenAI Chat Completions 的模型 ID。

curl 直接发送 HTTP 请求，所以这里填写完整路径；Python SDK 和部分客户端会自己拼接路径，填法不同。

先运行 curl --version。下面的 --fail-with-body 需要 curl 7.76.0 或更新版本。macOS 默认可能是 Zsh，先输入 bash 切换到 Bash，再执行后面的命令。

2. 保存请求内容

新建一个空的练习目录，在其中保存 request.json。将 YOUR_MODEL_ID 替换成刚才复制的真实模型 ID：

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "请把这句话改成简短工作通知：周五下午两点讨论新版首页，请提前准备三个建议。"
    }
  ],
  "stream": false
}

先用一个短文本任务。第一次不要同时添加图片、工具或复杂参数，否则失败后很难确定是哪一项不匹配。

3. 发送请求

在 request.json 所在目录执行下面整段 Bash 命令。密钥会在运行时读取，输入过程不显示字符，也不用写进 JSON 文件：

read -r -s -p '粘贴 TokenDance API Key，然后按回车：' TOKENDANCE_API_KEY
printf '\n'
curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 120 \
  'https://tokendance.space/gateway/v1/chat/completions' \
  --header "Authorization: Bearer $TOKENDANCE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  --output response.json \
  --write-out '\nHTTP 状态：%{http_code}\n'
curl_exit=$?
unset TOKENDANCE_API_KEY
printf 'curl 退出码：%s\n' "$curl_exit"
if [ -f response.json ]; then
  cat response.json
fi

response.json 保存响应正文，终端显示 HTTP 状态和 curl 退出码。--fail-with-body 会让 HTTP 错误返回非零退出码，同时保留错误正文，便于看清具体原因。

超时代表客户端没有等到完整结果，不等于服务端一定没有处理请求。先看调用日志，再决定是否重试。

4. 判断有没有真正成功

非流式对话结果通常可以从下面几个位置读取：

HTTP 200、没有错误字段且存在有效回答，说明这次文本请求有了正常结果。再到 TokenDance 的调用日志，按时间核对模型、状态与用量。实际扣费以平台账单为准，不能直接把 Token 数当作金额。

5. 报错时先看状态，再读正文

如果 curl 能成功、同一个模型在客户端失败，下一步重点核对客户端的基础地址、协议类型和模型选择。也可以继续用 Python SDK把这条请求接入脚本。

参考资料

参数核对日期：2026-09-28。命令用于读者自行验证，未展示或声称生产接口实测结果。

• TokenDance：OpenAI Chat Completions
• curl 官方手册