anthropic api

Claude Code 使用 Anthropic Messages API 与 Claude AI 通信。

API 配置

认证

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

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

API Key 来源

1. 环境变量 ANTHROPIC_API_KEY

2. 配置文件 .kiro/config.json

3. 系统密钥链（macOS Keychain）

Messages API

基本调用

const response = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 8192,
  system: systemPrompt,
  messages: [
    { role: 'user', content: 'Hello, Claude!' }
  ],
});

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

流式响应

const stream = await anthropic.messages.stream({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 8192,
  system: systemPrompt,
  messages: messages,
});

for await (const event of stream) {
  if (event.type === 'content_block_delta') {
    process.stdout.write(event.delta.text);
  }
}

工具调用

const response = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 8192,
  system: systemPrompt,
  messages: messages,
  tools: [
    {
      name: 'readFile',
      description: 'Read a file from the filesystem',
      input_schema: {
        type: 'object',
        properties: {
          path: { type: 'string', description: 'File path' }
        },
        required: ['path']
      }
    }
  ],
});

模型选择

可用模型

const MODELS = {
  'claude-3-5-sonnet-20241022': {
    contextWindow: 200000,
    maxOutput: 8192,
    cost: { input: 3, output: 15 }, // per million tokens
  },
  'claude-3-opus-20240229': {
    contextWindow: 200000,
    maxOutput: 4096,
    cost: { input: 15, output: 75 },
  },
  'claude-3-haiku-20240307': {
    contextWindow: 200000,
    maxOutput: 4096,
    cost: { input: 0.25, output: 1.25 },
  },
};

模型配置

{
  "model": "claude-3-5-sonnet-20241022",
  "temperature": 0.7,
  "maxTokens": 8192
}

Prompt Caching

启用缓存

const response = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  system: [
    {
      type: 'text',
      text: STATIC_PROMPT,
      cache_control: { type: 'ephemeral' }, // 缓存这部分
    },
    {
      type: 'text',
      text: dynamicPrompt,
    },
  ],
  messages: messages,
});

缓存效果

• 首次调用: 正常计费

• 缓存命中: 90% 折扣

• 缓存有效期: 5 分钟

缓存统计

interface CacheStats {
  cacheCreationInputTokens: number;
  cacheReadInputTokens: number;
  inputTokens: number;
  outputTokens: number;
}

const stats = response.usage;
console.log(`Cache hit rate: ${stats.cacheReadInputTokens / stats.inputTokens * 100}%`);

错误处理

API 错误类型

try {
  const response = await anthropic.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.APIError) {
    console.error('API Error:', error.status, error.message);
    
    if (error.status === 429) {
      // 速率限制
      await sleep(1000);
      return retry();
    } else if (error.status === 500) {
      // 服务器错误
      return retry();
    }
  }
}

重试策略

async function callWithRetry(
  fn: () => Promise<any>,
  maxRetries: number = 3
): Promise<any> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // 指数退避
      await sleep(1000 * Math.pow(2, i));
    }
  }
}

速率限制

限制规则

• 请求数: 50 请求/分钟

• Token 数: 40,000 tokens/分钟

• 并发数: 5 个并发请求

处理速率限制

class RateLimiter {
  private queue: Array<() => Promise<any>> = [];
  private running = 0;
  private maxConcurrent = 5;
  
  async execute<T>(fn: () => Promise<T>): Promise<T> {
    while (this.running >= this.maxConcurrent) {
      await sleep(100);
    }
    
    this.running++;
    try {
      return await fn();
    } finally {
      this.running--;
    }
  }
}

Token 计数

估算 Token 数

function estimateTokens(text: string): number {
  // 粗略估算：1 token ≈ 4 字符
  return Math.ceil(text.length / 4);
}

function estimateMessageTokens(messages: Message[]): number {
  let total = 0;
  
  for (const message of messages) {
    total += estimateTokens(JSON.stringify(message));
  }
  
  return total;
}

Token 预算管理

const TOKEN_BUDGET = {
  total: 200000,
  systemPrompt: 20000,
  conversation: 150000,
  toolResults: 20000,
  reserved: 10000,
};

function checkTokenBudget(messages: Message[]): boolean {
  const used = estimateMessageTokens(messages);
  return used < TOKEN_BUDGET.total - TOKEN_BUDGET.reserved;
}

成本追踪

计算成本

interface UsageStats {
  inputTokens: number;
  outputTokens: number;
  cacheReadTokens: number;
  cacheCreationTokens: number;
}

function calculateCost(usage: UsageStats, model: string): number {
  const pricing = MODELS[model].cost;
  
  const inputCost = usage.inputTokens * pricing.input / 1_000_000;
  const outputCost = usage.outputTokens * pricing.output / 1_000_000;
  const cacheCost = usage.cacheReadTokens * pricing.input * 0.1 / 1_000_000;
  
  return inputCost + outputCost + cacheCost;
}

成本统计

class CostTracker {
  private totalCost = 0;
  private requests = 0;
  
  track(usage: UsageStats, model: string): void {
    const cost = calculateCost(usage, model);
    this.totalCost += cost;
    this.requests++;
  }
  
  getStats() {
    return {
      totalCost: this.totalCost,
      requests: this.requests,
      avgCost: this.totalCost / this.requests,
    };
  }
}

最佳实践

1

使用 Prompt Caching

将静态内容标记为可缓存：

system: [
  { type: 'text', text: STATIC_RULES, cache_control: { type: 'ephemeral' } },
  { type: 'text', text: STATIC_TOOLS, cache_control: { type: 'ephemeral' } },
  { type: 'text', text: dynamicContext },
]

2

批量处理

合并多个小请求：

// ❌ 多次调用
for (const file of files) {
  await analyzeFile(file);
}

// ✅ 批量处理
await analyzeFiles(files);

3

流式响应

使用流式 API 提升用户体验：

const stream = anthropic.messages.stream({...});

for await (const event of stream) {
  // 实时显示响应
  updateUI(event);
}

4

错误恢复

实现健壮的错误处理：

try {
  return await anthropic.messages.create({...});
} catch (error) {
  if (isRetryable(error)) {
    return await retry();
  }
  throw error;
}

下一步

• 了解 MCP 协议 的工具集成

• 查看 工具 API 的开发接口

• 探索 用户数据 的收集范围