AI API 快速入门：从 API Key 到第一次调用

开始前先认识四个名词

Base URL 是 API 服务地址，API Key 是访问凭证，模型名决定调用哪个能力，端点决定请求采用哪种协议。四者必须配套；只替换模型名，不能把 OpenAI、Anthropic 和 Gemini 的请求体随意混用。聊天网页会员通常也不等于开发者 API 凭证。

第一步：准备三个变量

在本站准备一枚 API Key，到模型广场复制一个支持目标端点的精确模型 ID，并确认账户余额或配额可用。密钥只放在服务端环境变量或密钥管理器中，不要写入网页、移动端安装包、Git 仓库、截图和普通日志。

本文示例使用本站推荐的 Authorization: Bearer。为兼容原生 SDK，本站 /v1/messages 也接受本站密钥形式的 x-api-key，Gemini /v1beta/models/... 路径也接受 x-goog-api-key。直连 Anthropic 还必须发送 anthropic-version，直连 Google 使用 x-goog-api-key；调用本站时始终使用本站创建的密钥，不要混用厂商密钥。

Copyexport BASE_URL="https://你的服务地址"
export API_KEY="你的本站密钥"
export MODEL_NAME="从模型广场复制的精确模型名"

BASE_URL 在本文中不包含末尾的 /v1。如果 SDK 配置已经带有 /v1，不要重复拼接成 /v1/v1。

第二步：发送最小请求

初次排查优先使用 curl，因为它能排除 SDK 版本、代理和自动重试带来的干扰。下面的 Chat Completions 请求只发送一个用户消息：

Copycurl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$MODEL_NAME\",\"messages\":[{\"role\":\"user\",\"content\":\"只回复：连接成功\"}]}"

HTTP 200 且响应中出现模型文本，说明域名、密钥、模型和基础协议已经连通。不要一开始就加入图片、工具、长上下文或十几个可选参数；每增加一种能力，都应单独验证。

第三步：读懂成功响应

Chat Completions 的正文通常位于 choices[0].message.content，finish_reason 表示停止原因，usage 记录输入和输出用量。若停止原因表示长度上限，答案可能被截断；若正文为空，还要检查工具调用、拒绝、安全拦截或协议特有的内容块。

Copy{
  "choices": [
    {
      "message": {"role": "assistant", "content": "连接成功"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15}
}

示例数字只用于解释字段，实际响应以目标模型与渠道为准。记录 HTTP 状态、请求 ID、返回 model、停止原因、用量和耗时，比只保存最终文字更利于排障和计费核对。

第四步：选择正确协议

• 需要广泛 SDK 兼容和 messages 结构时，阅读 OpenAI 兼容 API 指南。
• 需要 Claude 原生内容块和工具语义时，阅读 Anthropic Messages API 指南。
• 需要本站已适配的 Gemini GenerateContent 多模态 parts 时，阅读 Gemini API 指南。

OpenAI 官方为新项目优先介绍 Responses API；Google 已为新项目推荐 Interactions API，但本站当前公开的 Gemini 原生兼容路径确定是 generateContent 与 streamGenerateContent，不包含 /v1beta/interactions。厂商“推荐接口”与网关“已适配接口”不是一回事，迁移前必须做字段级测试。

从其他 OpenAI 兼容服务迁移

先保持 /v1/chat/completions、messages 和最小请求体不变，只替换 SDK 的 base_url、本站 API Key 与模型广场中的精确模型 ID。若 SDK 的 base_url 已包含 /v1，不要再追加一次。最小文本请求通过后，再逐项回归流式事件、工具调用、图片输入、结构化输出、停止原因和用量字段；本站不保证复刻原服务的每个扩展参数，也不要只改模型名就切换到 Responses、Anthropic 或 Gemini 原生协议。

第五步：按状态码排错

400 多为 JSON、字段或上下文问题；401 检查密钥；403 检查权限；404 检查 Base URL、路径和模型名；413 表示请求体过大；429 可能是临时限流，也可能是余额或配额问题。5xx 要先读错误正文再分类：过载可能是临时故障，但 Gemini GenerateContent 的输入或上下文过长也可能表现为 500 或 504。先保留脱敏后的错误类型、消息和请求 ID，再查阅 API 报错排查指南。

只有临时 429、网络错误和部分 5xx 适合有限重试。优先遵循 Retry-After，否则使用带随机抖动的指数退避，并同时限制最大次数与总时长。400、401、403 和余额不足不会因为高频重试自动恢复。

第六步：控制费用与密钥风险

为单个用户设置并发、每分钟请求、每日用量和最大输出限制；开发环境从低成本模型和短输入开始。不要把完整请求和响应无界写入日志，尤其是图片 Base64、音频、文件、个人数据和工具结果。密钥泄露后应立即撤销并轮换。

上线前检查清单

• 固定已经验证的模型 ID、端点和必要参数，保存可回归的请求样本。
• 为连接、首字节和总请求设置合理超时，流式响应按完整 SSE 事件解析。
• 对临时失败做有限重试，对非幂等写操作使用幂等键或业务去重。
• 记录请求 ID、状态码、停止原因、用量和延迟，但对密钥与个人数据脱敏。
• 设置用户级费用上限、异常告警和降级模型，并定期核对官方弃用公告。