第一次调用 AI API:从环境变量到检查响应

用一条小请求理解 API 端点、密钥、模型 ID、状态码与用量,并说明 OpenAI 兼容接口的边界。

2026-11-03 · FreeTokenBox · 核查方法

第一次接入时,先让一个最小请求成功,再接入编辑器、Agent 或网页。这样可以区分账户权限、模型名字与客户端配置三类问题。

准备四项配置

准备 API 基地址、密钥、模型 ID 和任务接口。OpenAI 兼容通常表示部分请求格式相近,不代表模型名称、工具调用、图片输入和所有参数完全一样。

以下使用 Groq 官方公开端点作为请求结构示例。模型可用性与免费资格需要先在账户中确认。示例没有由本站使用真实密钥执行,也不保证你的账户具有相同权限。

用环境变量保存密钥

在自己的终端交互式读取密钥,可以避免把它直接写入命令历史。不要把真实值提交到 Git、截图或粘贴到公开问答。

read -r -s GROQ_API_KEY
export GROQ_API_KEY
export MODEL_ID='填写控制台中当前可用的模型ID'
curl --fail-with-body --max-time 30 \
  https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hello in one sentence.\"}],\"max_tokens\":64}"

先执行 read 命令、输入密钥并回车,再继续后面的命令。MODEL_ID 要替换为官方目录里的准确 ID;不要复制旧文章的模型名。也不要把不可信输入直接拼进 shell 命令。

成功不只看有没有文本

检查 HTTP 是否为 2xx、返回是否为预期 JSON,以及 choices 和 usage 等字段是否符合所用接口文档。记录请求的时间、模型和状态码即可;调试日志不必保存密钥或完整用户输入。

出错后按层排查

401 优先查密钥和 Authorization 格式;模型不存在时查模型 ID 与账户权限;429 查配额、并发和重置时间。客户端显示“连接失败”时,先单独运行最小请求,避免同时改端点、代理和模型配置。

接入网页时的边界

不要把这个示例直接放进浏览器代码。浏览器中的密钥会暴露给访问者。公共网页应由后端调用提供方,并限制请求体大小、超时、频率和每日预算。长期密钥只由服务端环境变量读取。

官方参考

Groq Quickstart 与 OpenAI Compatibility。该示例解释接入方法,不要求购买服务。