API 怎么配置：从 API Key、Base URL 到第一次调用

先把字段、协议和最终路径分开

下面的地址只是结构示例，不是可以直接调用的服务地址。真正值以服务商当前控制台和对应协议文档为准。

这篇教程解决什么问题

开始前准备

1. 确定客户端和协议：OpenAI Responses、OpenAI Chat Completions、Anthropic Messages，或服务商另行定义的协议。
2. 从同一份当前说明复制 Base URL、API Key 类型、模型 ID 和必填请求头。
3. Windows 准备 PowerShell 7 或系统自带 curl.exe；macOS/Linux 准备 curl。
4. 准备一个只返回短文本的低风险测试，不要用真实业务数据。

从控制台到客户端的 6 步流程

先用最小请求验证 API

下面的命令是教学示例，不代表某个账户已经调用成功。把同一服务当前文档中的 Base URL、Key 和模型 ID 替换进去；如果服务只支持 Responses 或 Anthropic Messages，选择对应分支。命令会把响应头保存为 response.headers、正文保存为 response.json，分享前必须脱敏。

# 教学示例：请先替换 3 个占位符，并确认服务商支持 Chat Completions
$env:API_BASE_URL = "https://api.example.com/v1"
$env:API_KEY = "<YOUR_API_KEY>"
$env:MODEL_ID = "<MODEL_ID>"

$uri = "$($env:API_BASE_URL.TrimEnd('/'))/chat/completions"
$body = @{
  model = $env:MODEL_ID
  messages = @(@{ role = "user"; content = "Reply with exactly OK." })
  max_tokens = 16
} | ConvertTo-Json -Depth 5
$body | Set-Content -LiteralPath request.json -Encoding utf8NoBOM

curl.exe --silent --show-error --dump-header response.headers --output response.json --write-out "\nHTTP %{http_code}" --request POST $uri --header "Authorization: Bearer $env:API_KEY" --header "Content-Type: application/json" --data-binary "@request.json"

# 预期：HTTP 200 + 当前协议的 JSON 响应。不要把真实 Key 提交到脚本或日志。

# 教学示例：请先替换 3 个占位符，并确认服务商支持 Chat Completions
export API_BASE_URL="https://api.example.com/v1"
export API_KEY="<YOUR_API_KEY>"
export MODEL_ID="<MODEL_ID>"

cat > request.json <<JSON
{"model":"$MODEL_ID","messages":[{"role":"user","content":"Reply with exactly OK."}],"max_tokens":16}
JSON

curl --silent --show-error --write-out "\nHTTP %{http_code}\n" \
  --request POST "${API_BASE_URL%/}/chat/completions" \
  --dump-header response.headers --output response.json \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

# 预期：HTTP 200 + 当前协议的 JSON 响应。

# 仅当当前服务/客户端明确支持 OpenAI Responses 时使用；请替换下面 3 个占位符
$env:API_BASE_URL = "https://api.example.com/v1"
$env:API_KEY = "<YOUR_API_KEY>"
$env:MODEL_ID = "<MODEL_ID>"
$uri = "$($env:API_BASE_URL.TrimEnd('/'))/responses"
$body = @{ model = $env:MODEL_ID; input = "Reply with exactly OK."; max_output_tokens = 16 } | ConvertTo-Json
$body | Set-Content -LiteralPath request.json -Encoding utf8NoBOM
curl.exe --silent --show-error --dump-header response.headers --output response.json --write-out "\nHTTP %{http_code}" --request POST $uri --header "Authorization: Bearer $env:API_KEY" --header "Content-Type: application/json" --data-binary "@request.json"

# 预期：HTTP 200 + Responses 格式 JSON；不要把它当作 Chat Completions 响应解析。

# 仅当服务商明确提供 Anthropic Messages 兼容入口时使用
export API_BASE_URL="https://api.example.com"
export API_KEY="<YOUR_API_KEY>"
export MODEL_ID="<MODEL_ID>"

cat > request.json <<JSON
{"model":"$MODEL_ID","max_tokens":16,"messages":[{"role":"user","content":"Reply with exactly OK."}]}
JSON

curl --silent --show-error --write-out "\nHTTP %{http_code}\n" \
  --request POST "${API_BASE_URL%/}/messages" \
  --dump-header response.headers --output response.json \
  --header "x-api-key: $API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data-binary @request.json

# 预期：HTTP 200 + Anthropic Messages 格式 JSON。

怎样判断这次调用真的成功

先看命令末尾的 HTTP 状态，再打开保存的响应文件。状态码只说明 HTTP 层结果，不能代替协议和内容检查。

• 响应的 Content-Type 与所选协议一致，不是登录页或 WAF HTML。
• 响应里的模型、输出字段和错误结构符合当前协议。
• 保存了 HTTP 状态、错误代码、时间和 request ID，但没有保存 Key、Cookie 或真实业务输入。

最小请求成功后，再迁移到 Codex 或 Claude Code

把已经验证的四项内容逐字迁移：Base URL、认证方式、模型 ID、协议。Codex 的 provider 配置与 Claude Code 的环境变量不是同一套字段，不能把一方的配置块直接粘到另一方。

配置不通时按证据分流

401 Unauthorized 或 invalid_api_key

先确认请求头类型、Key 是否完整、是否已撤销，以及当前终端和客户端是否仍读取旧变量；不要在排错消息中回显 Key。

403 Forbidden

Key 可能有效，但账户、模型、组织、地区或网关策略没有目标资源权限。重复生成 Key 通常不能解决授权策略。

404 Not Found 或路径重复

打印最终 URL，检查是否出现 /v1/v1、把控制台地址当 Base URL，或用 Responses 客户端请求了 Chat Completions 路径；再核对模型 ID。

400、422 或响应结构错误

地址和认证可能已通过，但请求体不符合该协议。对照当前接口文档检查字段名、必填项、模型 ID 和请求头，不要只换模型。

429 Too Many Requests 或余额不足

区分频率/并发限制和账户额度。前者按 Retry-After 或服务建议退避，后者需要处理余额或消费上限，盲目重试不会增加额度。

200 但返回 HTML、登录页或奇怪 JSON

HTTP 成功只说明拿到了响应；检查 Content-Type、响应结构和最终域名，确认没有落到控制台、WAF 或代理错误页。

无状态码超时

按 DNS、TCP、TLS、HTTP 首包和流式中断分层记录；网页能打开不能证明 API 端口、认证和流式接口都可用。

每轮只改一个因素：地址、协议、Key、模型、并发或客户端配置来源。否则即使下一次成功，也无法知道真正修复了什么。

完成后的验收标准

• 协议、客户端追加规则和最终 POST URL 已写下来。
• Base URL、认证方式、模型 ID 和必填请求头来自同一份当前说明。
• 真实 Key 只存在于受控环境变量或客户端安全存储。
• 最小请求返回预期协议的 JSON，而不是网页 HTML。
• HTTP 状态、错误代码、时间和 request ID 已脱敏保存。
• 客户端使用同一套字段复测通过，旧配置来源没有覆盖新值。

资料来源与动态字段说明

接口路径、模型、价格、额度和网关能力会变化。下面的官方文档用于解释协议和字段，服务商控制台用于确定你当前账户真正能用的值。页面内容按 2026-10-12 的编辑范围整理，未把本站实时调用记录写成实测结果。

• OpenAI API Authentication 官方文档

  用于核对 Bearer API Key 的认证概念；具体兼容网关仍以其当前文档为准。

• OpenAI Responses API 官方参考

  用于核对 Responses 的请求路径、模型和 input 字段。

• Anthropic Messages API 官方文档

  用于核对 Messages 的请求路径、x-api-key、anthropic-version 和请求体结构。

• 小贺API控制台

  Base URL、模型、价格、额度和协议字段可能变化；本文不把控制台动态值写死。

下一步