前言

Claude 是 Anthropic 推出的大语言模型，因其出色的推理能力和安全性设计在开发者中获得关注。相比网页版本，通过 API 调用能将 Claude 的能力集成到自己的应用中，实现自动化处理、批量分析或构建智能工具。

如果你在国内环境开发，或使用第三方兼容服务平台接入 Claude API，本文将帮助你快速理解调用原理，完成环境配置，并在五分钟内跑通第一个请求。

环境配置：三个必需步骤

1. 获取 API 密钥与 Endpoint

通过第三方兼容平台接入时，需要：

• 在对应平台完成注册和身份验证
• 在后台生成 API 密钥（通常以 token 或 key 形式提供）
• 获取该平台的 API Endpoint 地址（格式如 https://api.example.com/v1）

关键提示：不同平台的 Endpoint 和密钥格式可能有差异。获取后应在平台文档中确认具体的请求路径和鉴权方式。

2. 配置编程环境（以 Python 为例）

安装 Anthropic 官方库或兼容库：

pip install anthropic

如果平台提供了定制化的 SDK，以平台文档为准。

3. 通过环境变量管理凭证

不要在代码中硬写密钥。使用环境变量：

# 在命令行或 .env 文件中设置
export CLAUDE_API_KEY="your_api_key_here"
export CLAUDE_API_ENDPOINT="https://api.example.com/v1"

Python 中读取：

import os

api_key = os.getenv("CLAUDE_API_KEY")
api_endpoint = os.getenv("CLAUDE_API_ENDPOINT")

最小代码：首个 API 请求

下面是一个完整的最小示例，可直接复制运行：

import os
from anthropic import Anthropic

# 从环境变量读取凭证
api_key = os.getenv("CLAUDE_API_KEY")
api_endpoint = os.getenv("CLAUDE_API_ENDPOINT", "https://api.anthropic.com/v1")

# 初始化客户端
# 如果使用第三方兼容平台，通常需要指定 base_url
client = Anthropic(
    api_key=api_key,
    base_url=api_endpoint  # 根据平台情况调整
)

# 发送第一个请求
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "请用一句话解释什么是 API"}
    ]
)

# 打印响应
print(message.content[0].text)

代码说明：

组件	说明
api_key	从平台获取的 API 密钥
base_url	API 网关地址，不同平台可能不同
model	指定使用的模型版本
max_tokens	限制单次响应的最大 token 数，控制输出长度和成本
messages	消息列表，每条消息包含 role（user/assistant）和 content

核心参数详解

model（必需）

指定调用的模型。常见选项：

• claude-3-5-sonnet-20241022：平衡性能和成本，推荐首选
• 其他版本由平台提供，具体支持的模型列表请查阅平台文档

# 支持的模型可通过以下方式验证
# 在平台文档中查看最新可用模型列表
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

max_tokens（推荐）

单次响应的 token 上限。参考标准：

• 1 个 token ≈ 4 个英文字符
• 1 个 token ≈ 1-2 个中文字符

设置此参数可防止意外的长输出和额度消耗：

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=2048,  # 限制输出长度
    messages=[...]
)

temperature（可选，默认 1.0）

控制生成结果的随机性，取值范围 0-2：

• 0 附近：输出稳定保守，适合需要确定答案的任务（如代码生成、数据分析）
• 1.0 附近：平衡创意和稳定性，通用选择
• 2 附近：输出多样化创意，适合头脑风暴场景

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    temperature=0.5,  # 降低随机性，提高输出稳定性
    messages=[...]
)

system（可选）

系统提示词，用于设定 Claude 的角色和行为准则：

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    system="你是一位资深的技术文档编写专家。回答时请简洁专业，避免冗余。",
    messages=[
        {"role": "user", "content": "什么是 REST API？"}
    ]
)

top_p（可选）

核采样参数，与 temperature 配合控制输出多样性。一般保持默认值即可。

实战：构建多轮对话

Claude API 支持完整的对话上下文管理。下面是一个多轮对话示例：

import os
from anthropic import Anthropic

# 初始化客户端
client = Anthropic(
    api_key=os.getenv("CLAUDE_API_KEY"),
    base_url=os.getenv("CLAUDE_API_ENDPOINT", "https://api.anthropic.com/v1")
)

# 维护对话历史
conversation_history = []

def chat(user_message):
    """发送消息并获取回复"""
    # 添加用户消息到历史
    conversation_history.append({
        "role": "user",
        "content": user_message
    })
    
    # 发送请求，包含完整对话历史
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=conversation_history
    )
    
    # 提取助手回复
    assistant_message = response.content[0].text
    conversation_history.append({
        "role": "assistant",
        "content": assistant_message
    })
    
    return assistant_message

# 开始对话
print("Q1:", chat("Python 中什么是装饰器？"))
print("Q2:", chat("能给我一个实际的例子吗？"))
print("Q3:", chat("这个例子中 @functools.wraps 的作用是什么？"))

关键点：

• 每次请求时，将完整的对话历史一并发送
• Claude 可基于上下文理解和回答后续问题
• 对话历史会累计 token 消耗，长对话可考虑定期清空或总结

常见错误排查

1. 认证错误：401 Unauthorized

症状：请求返回 401 错误

原因和解决：

# ❌ 错误示例：密钥为空或格式错误
client = Anthropic(api_key="")

# ✅ 正确做法：验证环境变量
import os
api_key = os.getenv("CLAUDE_API_KEY")
if not api_key:
    raise ValueError("CLAUDE_API_KEY 环境变量未设置")

client = Anthropic(api_key=api_key)

排查步骤：

• 检查环境变量是否正确设置：echo $CLAUDE_API_KEY
• 确认密钥在平台后台仍未过期或被撤销
• 验证密钥不含空格或换行符

2. 连接错误：Connection Error

症状：无法连接到 API 端点

原因和解决：

# ❌ 错误：Endpoint 地址错误或网络问题
client = Anthropic(
    api_key=api_key,
    base_url="https://wrong.endpoint.com"
)

# ✅ 正确：验证 Endpoint 并添加错误处理
from anthropic import Anthropic
import socket

try:
    client = Anthropic(
        api_key=api_key,
        base_url=os.getenv("CLAUDE_API_ENDPOINT")
    )
    # 发送测试请求
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=100,
        messages=[{"role": "user", "content": "test"}]
    )
except socket.gaierror:
    print("网络连接失败，检查 DNS 和网络配置")
except Exception as e:
    print(f"API 请求失败: {e}")

排查步骤：

• 确认 Endpoint URL 与平台文档一致
• 测试网络连接：ping api.example.com
• 检查防火墙和代理配置
• 查看平台是否有服务状态公告

3. 模型错误：Model Not Found

症状：返回 "model not found" 或类似错误

原因和解决：

# ❌ 错误：使用平台不支持的模型
message = client.messages.create(
    model="gpt-4",  # Claude API 不支持此模型
    max_tokens=1024,
    messages=[...]
)

# ✅ 正确：使用平台支持的模型
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",  # 确认此模型在平台支持列表中
    max_tokens=1024,
    messages=[...]
)

排查步骤：

• 在平台文档中确认可用的模型列表
• 检查模型名称拼写和版本号
• 咨询平台技术支持获取最新支持的模型

4. Token 超限：Context Length Exceeded

症状：请求返回错误提示 token 过多

解决：

# 监控对话历史的 token 数量
conversation_history = []
MAX_HISTORY_LENGTH = 8000  # token 上限

def chat_with_limit(user_message):
    conversation_history.append({
        "role": "user",
        "content": user_message
    })
    
    # 如果历史过长，移除早期消息（保留最后 N 条）
    if len(str(conversation_history)) > MAX_HISTORY_LENGTH:
        # 保留系统消息和最近 5 条消息
        conversation_history = conversation_history[-10:]
    
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=conversation_history
    )
    
    assistant_message = response.content[0].text
    conversation_history.append({
        "role": "assistant",
        "content": assistant_message
    })
    
    return assistant_message

成本管理与优化建议

合理设置 max_tokens

# ❌ 过大的 max_tokens 浪费配额
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=32000,  # 过大，不必要
    messages=[...]
)

# ✅ 根据任务需求设置
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,  # 大多数问答任务足够
    messages=[...]
)

优化 Prompt 减少重试

# ❌ 模糊的 Prompt，容易需要重复请求
messages=[{"role": "user", "content": "生成代码"}]

# ✅ 清晰的 Prompt，一次成功
messages=[
    {
        "role": "user", 
        "content": "用 Python 编写一个函数，接收列表参数，返回去重后的元素，保持原顺序"
    }
]

定期审查使用情况

# 记录 API 调用统计
import json
from datetime import datetime

def log_api_call(model, input_tokens, output_tokens):
    """记录 API 调用信息"""
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "model": model,
        "input_tokens": input_tokens,
        "output_tokens": output_tokens,
        "total_tokens": input_tokens + output_tokens
    }
    
    with open("api_usage.log", "a") as f:
        f.write(json.dumps(log_entry) + "\n")

# 在请求后调用
response = client.messages.create(...)
# log_api_call(model="claude-3-5-sonnet-20241022", 
#              input_tokens=response.usage.input_tokens,
#              output_tokens=response.usage.output_tokens)

进阶：流式响应与批量处理

流式响应（实时输出）

# 使用流式 API 实现实时响应
with client.messages.stream(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "请写一首诗"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

批量异步请求

import asyncio
from anthropic import AsyncAnthropic

async def batch_requests(prompts):
    """异步处理多个请求"""
    client = AsyncAnthropic(api_key=os.getenv("CLAUDE_API_KEY"))
    tasks = []
    
    for prompt in prompts:
        task = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=512,
            messages=[{"role": "user", "content": prompt}]
        )
        tasks.append(task)
    
    results = await asyncio.gather(*tasks)
    return results

# 运行
# prompts = ["Python 是什么？", "JavaScript 的用途？", "Go 语言的优势？"]
# results = asyncio.run(batch_requests(prompts))

总结

通过第三方兼容 API 网关调用 Claude，核心流程简洁明了：

1. 获取凭证：API 密钥和 Endpoint 地址
2. 环境配置：安装依赖，通过环境变量管理凭证
3. 初始化客户端：指定 base_url 以适配不同平台
4. 构造请求：确定 model、max_tokens 等关键参数
5. 发送请求：调用 messages.create()，处理响应

掌握这些基础后，你可以进一步探索多轮对话、流式响应和批量处理等高级功能。遇到错误时，按照本文的排查步骤逐一验证认证、连接和模型配置。