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

调用 AI API 需要匹配的 Base URL、API Key、模型名和端点；先用最小 curl 请求跑通，再处理错误、费用与密钥安全。

## 开始前先认识四个名词

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

## 第一步：准备三个变量

登录[令牌管理](https://api.tu-zi.com/console/token)创建本站 API Key，再打开[模型广场](https://api.tu-zi.com/pricing)，确认当前 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`；调用本站时始终使用本站创建的密钥，不要混用厂商密钥。

```bash
export BASE_URL="https://api.tu-zi.com"
export API_KEY="你的本站 API Key"
export MODEL_NAME="从登录后的模型广场复制、且支持 /v1/chat/completions 的精确模型 ID"
```

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

## 第二步：发送最小请求

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

```bash
curl "$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` 记录输入和输出用量。若停止原因表示长度上限，答案可能被截断；若正文为空，还要检查工具调用、拒绝、安全拦截或协议特有的内容块。

```json
{
  "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 指南](https://api.tu-zi.com/docs/api/openai)。
- 需要 Claude 原生内容块和工具语义时，阅读 [Anthropic Messages API 指南](https://api.tu-zi.com/docs/api/anthropic)。
- 需要本站已适配的 Gemini GenerateContent 多模态 `parts` 时，阅读 [Gemini API 指南](https://api.tu-zi.com/docs/api/gemini)。

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 报错排查指南](https://api.tu-zi.com/docs/use-cases/troubleshooting)。

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

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

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

## 上线前检查清单

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

## 适用场景

- 第一次调用 AI API
- 从其他 OpenAI 兼容服务迁移
- 上线前检查认证、费用与重试

## API 路径

- /v1/chat/completions
- /v1/responses
- /v1/messages
- /v1beta/models/{model}:generateContent
- /v1beta/models/{model}:streamGenerateContent

## 关联指南

- [OpenAI 兼容 API 调用指南](https://api.tu-zi.com/docs/api/openai): 本站 OpenAI 兼容接口使用 Bearer 令牌；Responses、Chat Completions 与媒体端点拥有不同对象和流式语义，需按目标模型选择。
- [Anthropic Messages API 调用指南](https://api.tu-zi.com/docs/api/anthropic): Messages API 使用 system、角色消息和内容块；直连 Anthropic 要求 `x-api-key` 与版本头，本站推荐统一 Bearer，同时兼容原生 `x-api-key`。
- [Gemini API 调用指南：GenerateContent、Live 与 Interactions](https://api.tu-zi.com/docs/api/gemini): 本站提供 GenerateContent 与 gemini-3.8-live 的 /v1beta/live 原生 WebSocket；Live 使用 setup 与 serverContent 协议，只支持语音输出，可开启配套转写。
- [AI API 通用错误码与排障指南](https://api.tu-zi.com/docs/use-cases/troubleshooting): 处理 AI API 错误时应同时解析 HTTP 状态、厂商业务码、错误类型、消息、重试提示和请求 ID；参数、鉴权、余额与硬配额错误先修复根因，只有临时限流、网络错误和确认属于瞬时故障的部分 5xx 才适合有限重试。

## 常见问题

### 已经购买聊天产品会员，还需要 API Key 吗？

通常需要。聊天产品与开发者 API 往往是不同产品，账号、余额和配额也可能分开；调用本站接口时请使用本站创建的 API Key。

### Base URL 后面要不要加 /v1？

取决于客户端填写方式。本文把 BASE_URL 当作站点根地址，并在请求路径中写出 /v1；如果 SDK 的 base_url 已包含 /v1，就不要重复拼接。

### 为什么返回 401？

本文推荐本站统一的 Authorization: Bearer；本站对应原生路径也兼容 Anthropic 的 x-api-key 和 Gemini 的 x-goog-api-key。确认请求头与路径匹配，密钥完整且未过期或撤销；不要在工单中发送完整密钥。

### 为什么返回 404 或“模型不存在”？

先确认 BASE_URL 和请求路径没有拼错，再从登录后的模型广场复制精确模型 ID，并确认模型明确支持当前端点。如果仍失败，检查该 Key 的分组、模型限制和使用日志，判断是模型不可见还是没有可用渠道。

### 收到 429 应该一直重试吗？

不应该。临时限流可按 Retry-After 或带随机抖动的指数退避进行有限重试；余额、配额或消费上限问题必须先处理账户状态。

### 怎样知道一次调用消耗了多少？

保存端点实际返回的 usage 或对应协议用量字段，再结合模型广场的当前计费说明核算。流式用量是否出现、位于哪个事件以及是否要显式开启取决于端点和渠道，不能假设一定有统一的最终 usage 事件。

## 参考来源

- OpenAI Developer Quickstart: https://developers.openai.com/api/docs/quickstart
- Migrate to the Responses API: https://developers.openai.com/api/docs/guides/migrate-to-responses
- Anthropic Get Started: https://platform.claude.com/docs/en/get-started
- Claude Authentication: https://platform.claude.com/docs/en/manage-claude/authentication
- Gemini API Getting Started: https://ai.google.dev/gemini-api/docs/get-started
- Gemini Interactions API Overview: https://ai.google.dev/gemini-api/docs/interactions-overview
- Gemini API Key Best Practices: https://ai.google.dev/gemini-api/docs/api-key

## 文档来源

来源: https://api.tu-zi.com/docs/use-cases/getting-started

核验日期: 2026-08-12

本文为文档接入参考。厂商原生接口与本站接口可能不同；请结合对应 API Reference 和模型广场确认本站地址、鉴权、模型 ID、分组与参数。本文不表示所有模型或上游服务均已通过实时调用验收。仅包含文档与示例，不包含当前用户的密钥或请求记录。