大模型 API 协议概述

本文档概述主流大模型厂商（OpenAI、Anthropic Claude、Google Gemini）的 API 设计，帮助开发者理解各平台的异同，选择合适的接入方案。

阅读本文你将了解

• 三大厂商 API 的核心差异
• 各厂商的模型能力和定价
• 如何根据场景选择合适的 API
• API 演进历史和发展趋势

什么是大模型 API？

大模型 API（Application Programming Interface）是大语言模型厂商提供的编程接口，允许开发者通过网络请求的方式调用云端的 AI 模型能力。与传统的软件 API 不同，大模型 API 的核心特点是：

1. 自然语言交互

传统 API 需要严格按照预定义的参数格式调用，而大模型 API 接受自然语言作为输入。你可以用人类语言描述需求，模型会理解并生成相应的回复。这种交互方式极大降低了 AI 能力的使用门槛。

2. 生成式输出

大模型 API 的输出不是固定的数据查询结果，而是模型根据输入”生成”的内容。每次调用即使输入相同，输出也可能略有不同（除非将 temperature 设为 0）。这种特性使其适合创意写作、对话等场景，但也带来了输出不确定性的挑战。

3. Token 计费模式

大模型 API 通常按照处理的 Token 数量计费。Token 是模型处理文本的基本单位，一个中文字符通常对应 1-2 个 Token，一个英文单词通常对应 1-4 个 Token。理解 Token 的概念对于成本控制至关重要。

4. 上下文窗口限制

每个模型都有上下文窗口（Context Window）的限制，即单次请求能处理的最大 Token 数。这个限制包括输入和输出的总和。超出限制的内容会被截断或导致请求失败。

三大厂商 API 对比

基本信息

认证方式详解：

• Bearer Token（OpenAI）：在 HTTP 请求的 Authorization 头中携带 Bearer sk-xxx 格式的 API Key。这是最常见的 REST API 认证方式，符合 OAuth 2.0 规范。

• x-api-key Header（Anthropic）：使用自定义的 HTTP 头 x-api-key 携带 API Key。这种方式更简洁，但不符合标准的 OAuth 规范。Anthropic 同时要求携带 anthropic-version 头指定 API 版本。

• URL 参数 / OAuth（Google）：Google 提供两种认证方式。简单场景可以在 URL 中添加 ?key=xxx 参数；企业场景建议使用 OAuth 2.0 或 Service Account 认证，与 Google Cloud 生态深度集成。

核心端点

端点设计理念差异：

• OpenAI 采用 RESTful 风格，资源路径清晰（/chat/completions、/embeddings），流式输出通过参数控制。这种设计便于理解和使用，也成为了行业事实标准，许多第三方模型都兼容 OpenAI 格式。

• Anthropic 设计更简洁，核心只有 /messages 一个端点。所有对话相关功能都通过这个端点完成，通过请求体参数区分不同功能。这种设计减少了端点数量，但需要更多参数来控制行为。

• Google 采用 RPC 风格的端点命名（generateContent、streamGenerateContent），动词直接体现在路径中。流式和非流式使用不同端点，这种设计更符合 Google 的 API 设计规范，但与 REST 风格有所不同。

模型能力对比

能力详解：

• 上下文窗口：这是模型能”记住”的信息量。128K Token 约等于一本 200 页的书，200K 约等于 300 页，而 Gemini 的 2M 上下文可以处理整本长篇小说或大型代码库。但需注意，上下文越长，成本越高，响应也可能变慢。

• 多模态输入：指模型能处理的输入类型。GPT-4o 和 Claude 主要支持文本和图像，Claude 额外支持 PDF 直接解析。Gemini 的多模态能力最强，可以直接处理视频和音频文件，这在视频分析、会议记录等场景非常有用。

• 工具调用（Tool Calling）：允许模型在对话中调用外部函数或 API。例如，模型可以调用天气 API 获取实时天气，或调用数据库查询信息。这是构建 AI Agent 的核心能力。

• JSON 模式：强制模型输出有效的 JSON 格式，便于程序解析。在需要结构化输出的场景（如信息提取、数据转换）非常有用。

• 代码执行：Gemini 独有的能力，模型可以在沙箱环境中执行生成的代码并返回结果。这对于数据分析、数学计算等场景非常强大。

• 网页搜索：模型可以实时搜索互联网获取最新信息，解决训练数据截止日期的问题。

API 演进历史

了解 API 的演进历史有助于理解当前设计的来龙去脉，也能帮助预判未来的发展方向。

OpenAI

2020.06  GPT-3 API (Completions)
    ↓    首个大规模商用 LLM API，采用"补全"模式
2022.11  ChatGPT 发布
    ↓    对话式 AI 引爆全球关注
2023.03  GPT-4 + Chat Completions API
    ↓    引入 messages 数组，支持多轮对话
2023.06  Function Calling
    ↓    模型可调用外部函数，Agent 能力起步
2023.11  GPT-4 Turbo (128K)
    ↓    上下文窗口大幅扩展，JSON 模式
2024.05  GPT-4o
    ↓    多模态原生支持，速度提升 2 倍
2024.08  Structured Outputs
    ↓    保证输出符合 JSON Schema
2025.03  Responses API (新一代)
         内置工具、多模态输出、更简洁的设计

OpenAI 演进特点：从单纯的文本补全，逐步演进为多模态、多功能的对话平台。每次重大更新都会引入新的能力，同时保持向后兼容。Chat Completions API 已成为行业事实标准。

Anthropic Claude

2023.03  Claude API 发布
    ↓    主打安全、诚实、有帮助
2023.07  Claude 2
    ↓    100K 上下文，能力大幅提升
2024.03  Claude 3 (Opus/Sonnet/Haiku)
    ↓    三档模型满足不同需求
2024.06  Claude 3.5 Sonnet
    ↓    性能超越 Opus，成本更低
2024.10  Computer Use (Beta)
    ↓    模型可操作电脑界面
2024.10  Claude 3.5 Sonnet (新版)
    ↓    持续优化，代码能力增强
2025.05  Claude 4 Sonnet
         新一代模型，能力全面提升

Claude 演进特点：Anthropic 专注于模型安全性和可控性，API 设计相对稳定。Claude 3 引入的三档模型策略（Opus/Sonnet/Haiku）让用户可以根据任务复杂度选择合适的模型，平衡性能和成本。

注：Claude 模型持续更新，请查阅 官方模型页面 获取最新信息。

Google Gemini

2023.12  Gemini 1.0 Pro
    ↓    Google 首个统一多模态模型
2024.02  Gemini 1.5 Pro (1M 上下文)
    ↓    突破性的超长上下文能力
2024.05  Gemini 1.5 Flash
    ↓    轻量快速版本，成本极低
2024.09  Gemini 1.5 Pro (2M 上下文)
    ↓    上下文窗口再次翻倍
2024.12  Gemini 2.0 Flash
         新架构，原生多模态输出

Gemini 演进特点：Google 的优势在于多模态和超长上下文。2M 的上下文窗口远超竞争对手，可以处理整本书或数小时的视频。Flash 系列提供了极具竞争力的价格，适合大规模应用。

请求格式对比

三大厂商的请求格式各有特点，理解这些差异对于跨平台开发和协议转换至关重要。

OpenAI Chat Completions

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

OpenAI 格式特点：

• messages 是一个数组，包含完整的对话历史
• system 消息作为数组的第一个元素，与其他消息格式统一
• 角色（role）包括：system（系统设定）、user（用户输入）、assistant（模型回复）、tool（工具返回）
• 参数命名使用 snake_case 风格（如 max_tokens）
• 这种格式已成为行业标准，大多数第三方模型都兼容

Claude Messages

{
  "model": "claude-sonnet-4-20250514",
  "system": "You are helpful.",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

Claude 格式特点：

• system 提示词是独立的顶级字段，不在 messages 数组中
• 这种设计使系统提示更加突出，也便于实现 Prompt Caching
• messages 数组只包含 user 和 assistant 的对话
• 模型名称包含日期版本号（如 20250514），便于锁定特定版本
• max_tokens 是必填参数，不像 OpenAI 可以省略

Gemini generateContent

{
  "systemInstruction": {
    "parts": [{"text": "You are helpful."}]
  },
  "contents": [
    {"role": "user", "parts": [{"text": "Hello!"}]}
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 1000
  }
}

Gemini 格式特点：

• 使用 contents 而非 messages，parts 而非 content
• 内容被包装在 parts 数组中，每个 part 可以是不同类型（text、image 等）
• 这种设计天然支持多模态，一条消息可以包含多个不同类型的内容
• 生成参数放在 generationConfig 对象中，与内容分离
• 参数命名使用 camelCase 风格（如 maxOutputTokens）
• 角色使用 user 和 model（而非 assistant）

格式转换要点

从一种格式转换到另一种时，需要注意以下关键点：

响应格式对比

理解响应格式对于正确解析模型输出、处理错误和计算成本至关重要。

OpenAI

{
  "id": "chatcmpl-abc",
  "choices": [{
    "message": {"role": "assistant", "content": "Hi!"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 10, "completion_tokens": 5}
}

OpenAI 响应特点：

• choices 是数组，支持返回多个候选回复（通过 n 参数控制）
• finish_reason 表示生成停止的原因：
  • stop：正常完成
  • length：达到 max_tokens 限制
  • tool_calls：模型请求调用工具
  • content_filter：内容被安全过滤
• usage 包含 Token 使用统计，用于计费和监控
• id 是唯一标识符，可用于日志追踪和问题排查

Claude

{
  "id": "msg_abc",
  "content": [{"type": "text", "text": "Hi!"}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 10, "output_tokens": 5}
}

Claude 响应特点：

• content 是数组，每个元素有 type 字段，支持多种内容类型
• 文本内容的 type 为 text，工具调用的 type 为 tool_use
• stop_reason 的可能值：
  • end_turn：正常完成
  • max_tokens：达到长度限制
  • stop_sequence：遇到停止序列
  • tool_use：请求调用工具
• Token 统计使用 input_tokens 和 output_tokens，命名更直观

Gemini

{
  "candidates": [{
    "content": {"parts": [{"text": "Hi!"}], "role": "model"},
    "finishReason": "STOP"
  }],
  "usageMetadata": {"promptTokenCount": 10, "candidatesTokenCount": 5}
}

Gemini 响应特点：

• candidates 数组包含候选回复，结构与请求中的 contents 对应
• finishReason 使用大写枚举值：
  • STOP：正常完成
  • MAX_TOKENS：达到长度限制
  • SAFETY：安全过滤
  • RECITATION：检测到过度引用
• usageMetadata 中的字段使用 camelCase 命名
• 响应结构与请求结构高度一致，便于理解

响应解析最佳实践

# 通用的响应解析函数
def extract_text(response, provider):
    """从不同厂商的响应中提取文本内容"""
    if provider == "openai":
        return response["choices"][0]["message"]["content"]
    elif provider == "claude":
        # Claude 的 content 是数组，需要拼接
        return "".join(
            block["text"] for block in response["content"] 
            if block["type"] == "text"
        )
    elif provider == "gemini":
        return response["candidates"][0]["content"]["parts"][0]["text"]

适用场景分析

选择合适的 API 需要综合考虑功能需求、成本预算、合规要求等多个因素。以下是各厂商的优势场景分析。

OpenAI 适合

• 需要最广泛的生态兼容性：OpenAI 的 API 格式已成为行业标准，几乎所有 LLM 工具、框架都优先支持 OpenAI 格式。选择 OpenAI 意味着可以无缝使用 LangChain、LlamaIndex 等生态工具。

• 使用 GPT 系列模型：GPT-4o 在综合能力上仍然是顶级水平，特别是在复杂推理、创意写作方面表现出色。

• 需要 Whisper 语音转文字：OpenAI 的 Whisper API 是目前最准确的语音识别服务之一，支持多语言，价格合理。

• 需要 DALL-E 图像生成：如果应用需要 AI 生成图像，DALL-E 3 提供了高质量的图像生成能力。

• 使用 Assistants API 构建 Agent：OpenAI 的 Assistants API 提供了开箱即用的 Agent 框架，包括代码解释器、文件检索等内置工具。

Claude 适合

• 需要超长上下文（200K）：Claude 的 200K 上下文窗口可以处理整本书或大型代码库，适合文档分析、代码审查等场景。

• 处理 PDF 文档：Claude 原生支持 PDF 输入，可以直接理解 PDF 中的文字、图表、布局，无需预处理。

• 需要更安全、更诚实的回复：Anthropic 在模型安全性方面投入大量研究，Claude 更不容易产生有害内容，也更愿意承认自己的局限性。

• 代码生成和分析任务：Claude 在代码理解和生成方面表现优秀，特别是对于大型代码库的分析。

• 需要 Prompt Caching 降低成本：Claude 的 Prompt Caching 功能可以缓存重复的系统提示，在多轮对话或批量处理场景下可节省高达 90% 的输入成本。

Gemini 适合

• 需要超长上下文（2M）：Gemini 1.5 Pro 的 2M 上下文是目前最大的，可以处理数小时的视频或数十万行代码。

• 多模态任务（视频、音频）：Gemini 是唯一原生支持视频和音频输入的主流模型，可以直接分析视频内容、转录音频。

• 需要内置代码执行：Gemini 可以在安全沙箱中执行生成的代码，适合数据分析、数学计算等需要验证结果的场景。

• 与 Google Cloud 生态集成：如果已经使用 Google Cloud，Gemini 可以与 Vertex AI、BigQuery 等服务深度集成。

• 成本敏感场景（免费额度）：Gemini 提供慷慨的免费额度，Flash 系列的价格也极具竞争力，适合预算有限的项目。

定价对比

⚠️ 价格变动频繁，以下仅供参考，请以各厂商官网为准。

理解定价模型

大模型 API 通常按 Token 计费，需要理解以下概念：

• 输入 Token（Input/Prompt Tokens）：你发送给模型的内容，包括系统提示、对话历史、用户问题等
• 输出 Token（Output/Completion Tokens）：模型生成的回复内容
• 输出通常比输入贵：因为生成内容需要更多计算资源，输出价格通常是输入的 2-5 倍

价格参考 (每百万 token)

成本估算示例

假设一个聊天应用，每次对话：

• 系统提示：500 tokens
• 用户输入：100 tokens
• 模型回复：300 tokens

每次对话成本（以 GPT-4o-mini 为例）：

• 输入：600 tokens × $0.15/M = $0.00009
• 输出：300 tokens × $0.60/M = $0.00018
• 总计：约 $0.00027/次

如果每天 10,000 次对话，月成本约 $81。

成本优化建议

• Prompt Caching：Claude 支持缓存重复的系统提示，可节省 90% 输入成本。如果你的系统提示很长且固定，这个功能可以大幅降低成本。

• 选择合适模型：简单任务用 mini/haiku/flash，复杂任务再用旗舰模型。很多场景下，小模型的效果已经足够好。

• 控制输出长度：设置合理的 max_tokens 避免浪费。如果只需要简短回答，不要让模型生成长篇大论。

• 批量处理：部分厂商提供批量 API，价格更低。如果任务不需要实时响应，可以使用批量接口。

• 监控使用量：定期检查 Token 使用情况，识别异常消耗。设置预算告警，避免意外超支。

速率限制

速率限制（Rate Limiting）是 API 厂商为了保护服务稳定性而设置的请求频率限制。理解和处理速率限制是生产环境中的重要课题。

速率限制因账户等级、模型不同而异，以下为参考值。

速率限制的类型

OpenAI (Tier 1 示例)

OpenAI 采用分层（Tier）系统，新用户从 Tier 1 开始，随着使用量和付费金额增加，会自动升级到更高层级，获得更高的限额。Tier 5 用户的 RPM 可达数千。

升级到更高 Tier 可获得更高限额，详见 OpenAI Rate Limits

Claude

Claude 的限制相对保守，但可以通过联系 Anthropic 申请提升。企业用户通常可以获得更高的配额。

详见 Anthropic Rate Limits

Gemini (免费层)

Gemini 的免费层限制较严格，但付费用户限额大幅提升。通过 Google Cloud 的 Vertex AI 使用可以获得企业级的配额。

详见 Google AI Pricing

处理速率限制

当触发速率限制时，API 会返回 429 错误。正确的处理方式：

import time
from tenacity import retry, wait_exponential, retry_if_exception_type

@retry(
    wait=wait_exponential(multiplier=1, min=1, max=60),
    retry=retry_if_exception_type(RateLimitError)
)
def call_api_with_retry(messages):
    return client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages
    )

最佳实践：

• 实现指数退避重试（Exponential Backoff）
• 监控 API 响应头中的限额信息
• 在高并发场景使用请求队列
• 考虑使用多个 API Key 轮换

选择建议

按需求选择

按场景选择

相关文档

• 02-OpenAI Chat Completions API
• 03-OpenAI Responses API
• 04-Claude Messages API
• 05-Gemini API
• 06-传输协议对比
• 07-协议转换指南
• 08-SDK使用指南
• 09-错误处理与重试
• 17-安全与合规指南
• 18-国产模型介绍
• 26-术语表
• 27-MCP协议详解

官方资源

文档

• OpenAI: https://platform.openai.com/docs
• Claude: https://docs.anthropic.com
• Gemini: https://ai.google.dev/docs

SDK

• OpenAI Python: https://github.com/openai/openai-python
• Anthropic Python: https://github.com/anthropics/anthropic-sdk-python
• Google AI Python: https://github.com/google/generative-ai-python

状态页

• OpenAI: https://status.openai.com
• Anthropic: https://status.anthropic.com
• Google AI: https://status.cloud.google.com