首页 / 第六章

第六章：Anthropic API 使用教程

Anthropic API 让你可以在自己的应用中集成 Claude 的能力。本章从 API 基础到高级特性逐一讲解，包含 Python 和 Node.js 的完整代码示例。

6.1 API 密钥与鉴权

获取 API Key

访问 Anthropic Console（console.anthropic.com）
注册并完成账号验证
进入 API Keys 页面，点击「Create Key」
复制密钥（只显示一次，请妥善保存）

安全配置

# 方式一：环境变量（推荐）
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 方式二：.env 文件（本地开发）
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." >> .env
echo ".env" >> .gitignore

6.2 Messages API 基础

Python 示例

import anthropic

client = anthropic.Anthropic()  # 自动读取 ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="你是一名专业的代码审查员，擅长发现安全漏洞。",
    messages=[
        {"role": "user", "content": "请审查以下代码：\n```python\npassword = input()\nif password == '123456':\n    login()\n```"}
    ]
)

print(message.content[0].text)

Node.js 示例

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic(); // 自动读取 ANTHROPIC_API_KEY

const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  system: '你是一名专业的代码审查员，擅长发现安全漏洞。',
  messages: [
    { role: 'user', content: '请审查以下代码...' }
  ],
});

console.log(message.content[0].text);

关键参数说明

参数	类型	说明
`model`	string	模型 ID，如 `claude-sonnet-4-6`
`max_tokens`	number	输出 token 上限，必填
`system`	string	系统提示，设定角色和规则
`messages`	array	对话消息数组，role 为 user/assistant
`temperature`	0–1	创意度，默认 1，代码任务建议 0
`top_p`	0–1	核采样，与 temperature 二选一

6.3 流式响应

流式响应让输出逐字显示，适合聊天界面和长文本生成场景。

Python 流式

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一首关于代码的诗"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# 流结束后获取完整消息
final_message = stream.get_final_message()
print(f"\n\n用量：{final_message.usage}")

Node.js 流式（SSE）

const stream = await client.messages.stream({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: '写一首关于代码的诗' }],
});

// 逐 chunk 处理
for await (const chunk of stream) {
  if (chunk.type === 'content_block_delta' && chunk.delta.type === 'text_delta') {
    process.stdout.write(chunk.delta.text);
  }
}

const finalMessage = await stream.finalMessage();
console.log('\n用量：', finalMessage.usage);

6.4 Tool Use（工具调用）

Tool Use 让 Claude 可以调用你定义的函数，实现数据查询、计算、外部 API 调用等能力。

完整调用循环（Python）

import anthropic
import json

client = anthropic.Anthropic()

# 定义工具
tools = [
    {
        "name": "get_weather",
        "description": "获取指定城市的当前天气",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名称"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "温度单位"},
            },
            "required": ["city"],
        },
    }
]

messages = [{"role": "user", "content": "北京今天天气怎么样？"}]

# 第一轮：Claude 决定调用工具
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

# 处理工具调用
if response.stop_reason == "tool_use":
    tool_use_block = next(b for b in response.content if b.type == "tool_use")

    # 执行工具函数
    tool_result = {"temperature": 18, "condition": "晴天", "humidity": "45%"}

    # 将工具结果返回给 Claude
    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": json.dumps(tool_result, ensure_ascii=False),
        }]
    })

    # 第二轮：Claude 根据工具结果生成最终回答
    final_response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    print(final_response.content[0].text)

6.5 Vision（图像理解）

URL 方式

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "url",
                    "url": "https://example.com/screenshot.png",
                },
            },
            {"type": "text", "text": "这张截图中有哪些 UI 问题？"},
        ],
    }],
)
print(message.content[0].text)

Base64 方式（本地图片）

import base64

with open("diagram.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": image_data,
                },
            },
            {"type": "text", "text": "解释这个架构图"},
        ],
    }],
)

支持的图片格式：image/jpeg、image/png、image/gif、image/webp，单张最大 5MB，单次请求最多 20 张图。

6.6 Prompt Caching

Prompt Caching 将重复的长 prompt（如系统提示、大型文档）缓存在服务端，后续请求直接复用缓存，可降低 90% 输入 token 费用，并减少延迟。

启用方式

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是一名法律顾问助手。",
        },
        {
            "type": "text",
            "text": very_long_legal_document,  # 可能有几万 token 的长文档
            "cache_control": {"type": "ephemeral"},  # 标记此处需要缓存
        }
    ],
    messages=[{"role": "user", "content": "第 3 条第 2 款的含义是什么？"}],
)

缓存策略建议

场景	建议
多轮问答同一文档	将文档放在 system 末尾并标记缓存
固定工具集	将 tools 定义列表标记缓存
多用户共享系统提示	系统提示设为缓存，用户消息动态变化

ℹ️

缓存生效条件

缓存最小 token 数：Sonnet 模型为 1024 tokens，Haiku 为 2048 tokens。缓存有效期约 5 分钟，活跃使用可自动续期。可通过响应的 usage.cache_read_input_tokens 字段确认是否命中缓存。

6.7 SDK 完整示例

Python SDK：多轮对话封装

import anthropic
from typing import Optional

class ClaudeChat:
    def __init__(self, system: Optional[str] = None, model: str = "claude-sonnet-4-6"):
        self.client = anthropic.Anthropic()
        self.model = model
        self.system = system
        self.history: list = []

    def chat(self, user_message: str, max_tokens: int = 2048) -> str:
        self.history.append({"role": "user", "content": user_message})

        kwargs = {
            "model": self.model,
            "max_tokens": max_tokens,
            "messages": self.history,
        }
        if self.system:
            kwargs["system"] = self.system

        response = self.client.messages.create(**kwargs)
        assistant_message = response.content[0].text

        self.history.append({"role": "assistant", "content": assistant_message})
        return assistant_message

    def reset(self):
        self.history = []


# 使用示例
chat = ClaudeChat(system="你是一名 Python 专家，回答要简洁准确。")
print(chat.chat("什么是装饰器？"))
print(chat.chat("给我一个实际的使用例子"))  # 保持上下文

Node.js SDK：带重试的客户端封装

import Anthropic from '@anthropic-ai/sdk';

// SDK 内置自动重试（默认 2 次）
const client = new Anthropic({
  maxRetries: 3,
  timeout: 60 * 1000, // 60 秒超时
});

async function askClaude(prompt, options = {}) {
  const response = await client.messages.create({
    model: options.model ?? 'claude-sonnet-4-6',
    max_tokens: options.maxTokens ?? 1024,
    system: options.system,
    messages: [{ role: 'user', content: prompt }],
  });
  return response.content[0].text;
}

// 使用示例
const result = await askClaude('用一句话解释递归', {
  system: '用通俗易懂的方式回答，避免专业术语',
  maxTokens: 200,
});
console.log(result);