第一次 API 调用：10 行 curl

准备

你需要两样东西：一把可用的 key，一个能跑 curl 的终端。

先把 key 放进环境变量。它只活在当前 shell 会话里，关掉就没了——这正是我们要的。

export DOCAI_API_KEY="sk-..."      # 换成你自己的 key
export DOCAI_MODEL="your-model"    # 换成你账号里可用的模型名

不要把这两行写进 .env 再提交，也不要直接粘进会保存历史的命令里。为什么这么做，见 什么是 API Key。

发请求

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $DOCAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$DOCAI_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"用一句话解释什么是 token\"}]
  }"

把地址换成你所用服务的地址。请求体只有三个关键字段：model、messages，以及可选的 temperature。

看懂响应

你看到	意味着什么	下一步
200，choices[0].message.content 有文字	成功。content 就是回答，usage 是用量	看 usage 里的三个 token 数
401 / 403	鉴权这一步没过，请求没到模型	401 分情况排查
429	被限流，或余额/配额用尽	429 一直不退
200，但 content 为空、有 tool_calls	模型在调工具，不是出错	按工具调用的格式继续处理
连接超时、断流	网络或上游过载，不是参数问题	重试一次，仍失败再查状态页

usage 里通常有三个数：输入 token、输出 token、总 token。计费按前两个分别算，所以长输入和长输出不是一个价。

把 key 放对地方

正确顺序是：环境变量 → 代码读取 → 日志里打码。

• 本地开发：.env 文件，并把它写进 .gitignore。
• 服务器：用服务的环境变量配置，不要放进仓库。
• 日志：打印请求时把 Authorization 头整个抹掉。

自测

1. 为什么不能把 key 直接写在 curl 命令里执行？（提示：shell 历史会落盘）
2. 401 和 429 分别应该改什么？改错了会怎样？
3. usage 里输入 token 和输出 token 为什么要分开计？