大模型 API 接入指南：从零开始调用 GPT、Claude、Kimi

随着大语言模型（LLM）在各行各业的落地，越来越多的开发者需要通过 API 将 AI 能力集成到自己的产品中。本文将带你从零开始，了解大模型 API 的核心概念，掌握主流接入协议，并通过多语言代码示例完成第一次调用。

一、大模型 API 的基本概念

在开始接入之前，你需要理解三个关键概念：

API Key（密钥）

API Key 是你访问大模型服务的身份凭证，类似于一把钥匙。每个平台都会为你生成唯一的 Key，用于鉴权和计费。请务必妥善保管，不要将其硬编码到前端代码或公开仓库中。

Base URL（接口地址）

Base URL 是 API 服务的入口地址。不同平台的地址不同，例如：

• OpenAI 官方：https://api.openai.com/v1
• Claude 官方：https://api.anthropic.com
• 国内聚合平台：通常提供自定义的 Base URL，兼容 OpenAI 格式

使用聚合平台时，你只需要修改 Base URL，就能用同一套代码调用不同厂商的模型。

Token（令牌）

Token 是大模型处理文本的基本单位。一个中文汉字通常对应 1-2 个 Token，一个英文单词大约是 1 个 Token。API 的计费通常按输入 Token 和输出 Token 分别计算，理解 Token 机制有助于你控制成本。

二、主流接入协议

目前市面上主要有三种 API 协议，了解它们的差异能帮助你更高效地完成接入。

1. OpenAI Chat Completions 接口

这是目前最通用的协议，绝大多数国内外模型都兼容这一格式。核心端点为 /v1/chat/completions，请求体采用 messages 数组结构：

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "你好，请介绍一下自己。"}
  ]
}

GPT、Kimi、DeepSeek、通义千问等模型均支持此格式，是入门首选。

2. Claude Messages 接口

Anthropic 的 Claude 使用独立的 /v1/messages 端点，请求结构略有不同——system 消息单独作为顶层字段传递：

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": "你是一个有帮助的助手。",
  "messages": [
    {"role": "user", "content": "你好，请介绍一下自己。"}
  ]
}

此外，Claude 使用 x-api-key 请求头传递密钥，而非 OpenAI 风格的 Authorization: Bearer。许多聚合平台已将 Claude 封装为 OpenAI 兼容格式，降低了接入门槛。

3. OpenAI Responses 接口

OpenAI 于 2025 年推出了新的 /v1/responses 端点，作为 Chat Completions 的演进版本。它引入了更丰富的工具调用能力和内置工具（如网页搜索、文件搜索、代码解释器），适合构建复杂的 Agent 应用：

{
  "model": "gpt-4o",
  "input": "帮我搜索一下最新的 AI 新闻",
  "tools": [{"type": "web_search_preview"}]
}

如果你的场景以对话为主，Chat Completions 足够使用；如果需要构建具备工具调用能力的智能体，可以关注 Responses 接口。

三、实际接入步骤

第 1 步：获取 API Key

前往对应平台的开发者控制台注册账号并创建 API Key：

• OpenAI：platform.openai.com
• Anthropic：console.anthropic.com
• 聚合平台：注册后通常在「密钥管理」页面一键生成

第 2 步：配置环境变量

将 API Key 存储在环境变量中，避免泄露风险：

# Linux / macOS
export OPENAI_API_KEY="sk-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-key-here"

第 3 步：发送第一个请求

下面我们用三种方式完成第一次 API 调用。

四、多语言 SDK 示例

curl 示例

最直接的方式，适合快速验证接口连通性：

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "用一句话解释什么是 API"}
    ]
  }'

调用 Claude 的 curl 示例：

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话解释什么是 API"}
    ]
  }'

Python 示例（openai 库）

Python 是 AI 开发者最常用的语言，openai 库提供了简洁的调用方式：

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key-here",       # 建议从环境变量读取
    base_url="https://api.openai.com/v1"  # 切换聚合平台只需改这里
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "Python 有哪些优势？"}
    ],
    max_tokens=500
)

print(response.choices[0].message.content)

安装依赖：pip install openai

Node.js 示例

前端和全栈开发者可以使用 openai npm 包：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.openai.com/v1",  // 聚合平台替换此地址即可
});

async function main() {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [
      { role: "system", content: "你是一个有帮助的助手。" },
      { role: "user", content: "Node.js 适合做什么？" },
    ],
    max_tokens: 500,
  });

  console.log(response.choices[0].message.content);
}

main();

安装依赖：npm install openai

五、聚合 API 平台的优势

如果你需要同时使用多个模型（例如 GPT-4o 处理通用任务、Claude 处理长文本、Kimi 处理中文场景），逐一对接各家 API 会带来不小的管理负担。这时，聚合 API 平台的价值就体现出来了：

• 一个 Key 调用多模型：无需在多个平台分别注册和充值，一个 API Key 即可访问 GPT、Claude、Gemini、DeepSeek、Kimi 等数十种模型。
• 统一接口协议：所有模型统一封装为 OpenAI 兼容格式，切换模型只需修改 model 参数，无需改动业务代码。
• 统一计费与用量管理：在一个后台查看所有模型的调用量和费用，方便团队预算管控。
• 简化运维：不用担心某家 API 的证书更新、域名变更等问题，平台会统一处理。
• 更低的接入成本：部分聚合平台提供免费额度和更优惠的价格，适合个人开发者和初创团队。

使用聚合平台时，代码改动极小——只需替换 base_url 和 api_key：

# 从 OpenAI 官方切换到聚合平台，只改两行
client = OpenAI(
    api_key="sk-aggregator-key",
    base_url="https://api.your-aggregator.com/v1"
)

六、常见问题排查

在接入过程中，你可能会遇到以下问题：

401 Unauthorized

最常见的错误，通常由以下原因导致：

• API Key 填写错误或已过期——检查是否有多余的空格或换行符
• 请求头格式不对——OpenAI 使用 Authorization: Bearer sk-xxx，Claude 使用 x-api-key: sk-ant-xxx
• 账户余额不足——部分平台在余额为零时会返回 401 而非 402

请求超时（Timeout）

大模型生成较长内容时可能需要数十秒，建议：

• 将 HTTP 客户端的超时时间设置为 60 秒以上
• 使用流式输出（stream: true）降低首字等待时间
• 减少 max_tokens 参数值以缩短响应时间

模型不可用（Model Not Found）

• 确认模型名称拼写正确，注意大小写和版本号（如 gpt-4o 而非 gpt4o）
• 确认你的账户有权限访问该模型——部分高级模型需要单独申请
• 如果使用聚合平台，确认该平台已上线你需要的模型

中文乱码

• 确保请求和响应的编码均为 UTF-8
• 在 curl 中添加 -H "Content-Type: application/json; charset=utf-8"
• 检查终端或 IDE 的编码设置

总结

大模型 API 的接入并不复杂。理解 API Key、Base URL、Token 三个核心概念后，选择合适的协议（OpenAI 兼容格式是最通用的选择），配合 Python 或 Node.js SDK，几行代码就能完成调用。如果你需要同时使用多个模型，聚合 API 平台能显著降低接入和管理成本。

建议从一个简单的对话请求开始，逐步探索流式输出、函数调用、多模态输入等高级功能。动手试试吧，大模型的能力远比你想象的更容易获取。