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

> 在 Bash 终端用 curl 发送 OpenAI 兼容的 Chat Completions 请求，查看 HTTP 状态和返回结果，定位 401、404 与 429。以 TokenDance 为例。

- 原文：https://token.help/articles/api-first-request
- 作者：词元有方编辑部
- 成稿时间：2026-09-28T10:11:25.000Z
- 发布时间：2026-09-29T07:58:47.000Z
- 最后更新：2026-09-29T07:58:47.000Z
- 分类：接入教程
- 核验方式：已核对官方文档
- 核验时间：2026-09-28T00:00:00.000Z

引用本文请使用上方原文链接；配置与结论以文中版本和核验时间为准。来源内容的许可说明保留在正文中。

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

本文使用 **macOS / Linux 的 Bash 终端**，调用 TokenDance 的 OpenAI Chat Completions 接口。Windows 用户可以在 WSL 中跟做，或使用 [Python 版本](https://token.help/articles/python-openai-sdk-tokendance)。

## 1. 准备三个信息

在 [API 密钥页](https://tokendance.space/keys?utm_source=journal\&utm_medium=content\&utm_content=api-first-request)创建密钥，然后从[模型列表](https://tokendance.space/models?utm_source=journal\&utm_medium=content\&utm_content=api-first-request)复制支持 OpenAI Chat Completions 的模型 ID。

| 项目      | 本文使用的值                                                 |
| ------- | ------------------------------------------------------ |
| 完整请求地址  | `https://tokendance.space/gateway/v1/chat/completions` |
| API Key | 你的 TokenDance 密钥                                       |
| model   | 平台上的完整模型 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：

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

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

## 3. 发送请求

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

```bash
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. 判断有没有真正成功

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

| 字段                           | 用途               |
| ---------------------------- | ---------------- |
| `choices[0].message.content` | 模型生成的正文          |
| `choices[0].finish_reason`   | 这次生成的结束原因        |
| `usage`（若返回）                 | 接口返回的 Token 使用信息 |

HTTP 200、没有错误字段且存在有效回答，说明这次文本请求有了正常结果。再到 TokenDance 的[调用日志](https://tokendance.space/activity?utm_source=journal\&utm_medium=content\&utm_content=api-first-request)，按时间核对模型、状态与用量。实际扣费以平台账单为准，不能直接把 Token 数当作金额。

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

| 现象              | 排查动作                                    |
| --------------- | --------------------------------------- |
| 401             | 重新检查密钥，确认没有空格、没有被停用                     |
| 404             | 检查完整路径和模型 ID；根据错误正文区分路径不存在还是模型不可用       |
| 400             | 先确认 JSON 合法，再检查模型支持的字段和协议               |
| 429             | 查看具体限流说明，降低请求频率；若有 `Retry-After`，按其提示等待 |
| 5xx             | 保存时间和错误信息，检查服务状态后再尝试                    |
| HTTP 000 / 连接失败 | 检查网络、DNS、证书或超时信息；这不是服务端返回的 HTTP 状态码     |

如果 curl 能成功、同一个模型在客户端失败，下一步重点核对客户端的基础地址、协议类型和模型选择。也可以继续用 [Python SDK](https://token.help/articles/python-openai-sdk-tokendance)把这条请求接入脚本。

## 参考资料

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

- [TokenDance：OpenAI Chat Completions](https://tokendance.space/docs/protocol-openai-chat-completions)
- [curl 官方手册](https://curl.se/docs/manpage.html)

## 核验参考来源

- https://tokendance.space/docs/protocol-openai-chat-completions
- https://curl.se/docs/manpage.html