claude-api

Claude API（Anthropic Messages API）

状态：已可用于生产环境 | SDK：@anthropic-ai/[email protected]

---

快速入门（5 分钟）

Node.js

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

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

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Claude!' },
  ],
});

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

Cloudflare Workers

const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': env.ANTHROPIC_API_KEY,
    'anthropic-version': '2023-06-01',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});

const data = await response.json();
console.log(data.content[0].text);

加载 references/setup-guide.md，查看包含流式传输、缓存和工具的完整设置指南。

---

关键规则

务必做到 ✅

1. 使用环境变量存储 API 密钥（绝不要硬编码）
2. 明确设置 max_tokens（必需参数）
3. 固定模型版本（使用 claude-sonnet-4-5-20250929，而不是 claude-3-5-sonnet-latest）
4. 为重复内容启用提示词缓存（可节省 90% 成本）
5. 对较长的响应使用流式传输（stream: true），改善用户体验
6. 处理错误——为 429、529 错误实现重试逻辑
7. 验证输入——发送前清理用户消息
8. 监控成本——跟踪 Token 使用量
9. 设置超时——防止请求一直挂起
10. 正确使用工具——在后续消息中返回 tool_result

绝不要做 ❌

1. 绝不要在客户端代码中暴露 API 密钥
2. 绝不要省略 max_tokens——不设置时 API 会报错
3. 绝不要忽略 stop_reason——检查 tool_use、end_turn、max_tokens
4. 绝不要假设只有一个内容块——content 是一个数组
5. 绝不要使用过时的模型——固定到特定版本
6. 绝不要跳过错误处理——API 调用可能失败
7. 绝不要混淆消息角色——正确交替使用 user/assistant
8. 绝不要忽略速率限制——实现指数退避
9. 绝不要在日志或数据库中存储 API 密钥
10. 绝不要跳过输入验证——防止注入攻击

---

最常见的 3 个错误（预防 80% 的问题）

错误 #1：速率限制 429

症状：429 Too Many Requests: Number of request tokens has exceeded your per-minute rate limit

解决方案：根据 retry-after 响应头实现指数退避和重试

async function handleRateLimit(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.response?.headers?.['retry-after'];
        const delay = retryAfter ? parseInt(retryAfter) * 1000 : 1000 * Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

预防方法：监控速率限制响应头、升级套餐、实现退避

---

错误 #2：提示词缓存未生效

症状：尽管使用了 cache_control 块，成本仍然很高，且 cache_read_input_tokens: 0

解决方案：将 cache_control 放在至少包含 1024 个 Token 的最后一个块上

// ❌ Wrong - cache_control not at end
{
  type: 'text',
  text: DOCUMENT,
  cache_control: { type: 'ephemeral' },  // Wrong position
},
{
  type: 'text',
  text: 'Additional text',
}

// ✅ Correct - cache_control at end
{
  type: 'text',
  text: DOCUMENT + '\n\nAdditional text',
  cache_control: { type: 'ephemeral' },  // Correct position
}

预防方法：确保内容至少包含 1024 个 Token、保持缓存内容完全一致、监控用量

加载 references/prompt-caching-guide.md，查看完整的缓存策略。

---

错误 #3：工具调用响应格式错误

症状：invalid_request_error: tools[0].input_schema is invalid

解决方案：使用符合 JSON Schema 规范的有效工具架构

// ✅ Valid tool schema
{
  name: 'get_weather',
  description: 'Get current weather',
  input_schema: {
    type: 'object',           // Must be 'object'
    properties: {
      location: {
        type: 'string',       // Valid JSON Schema types
        description: 'City'   // Optional but recommended
      }
    },
    required: ['location']    // List required fields
  }
}

// ✅ Valid tool result
{
  type: 'tool_result',
  tool_use_id: block.id,      // Must match tool_use id
  content: JSON.stringify(result)  // Convert to string
}

预防方法：验证架构、确保 tool_use_id 完全匹配、将结果转换为字符串

加载 references/tool-use-patterns.md 和 references/top-errors.md，查看全部 12 个错误。

---

常见用例（快速示例）

流式响应

const stream = await client.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a story.' }],
});

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

加载：templates/streaming-chat.ts

---

提示词缓存（节省 90% 成本）

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'Long system prompt...',
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [{ role: 'user', content: 'Question?' }],
});

缓存有效期为 5 分钟，缓存 Token 可节省 90% 成本

加载：references/prompt-caching-guide.md 和 templates/prompt-caching.ts

---

工具调用（函数调用）

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  tools: [{
    name: 'get_weather',
    description: 'Get weather for a location',
    input_schema: {
      type: 'object',
      properties: { location: { type: 'string' } },
      required: ['location'],
    },
  }],
  messages: [{ role: 'user', content: 'Weather in SF?' }],
});

if (message.stop_reason === 'tool_use') {
  const toolUse = message.content.find(b => b.type === 'tool_use');
  // Execute tool and send result back...
}

加载：references/tool-use-patterns.md 和 templates/tool-use-basic.ts

---

视觉（图像理解）

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{
    role: 'user',
    content: [
      {
        type: 'image',
        source: {
          type: 'base64',
          media_type: 'image/jpeg',
          data: base64Image,
        },
      },
      { type: 'text', text: 'What is in this image?' },
    ],
  }],
});

支持：JPEG、PNG、WebP、GIF（最大 5 MB）

加载：references/vision-capabilities.md 和 templates/vision-image.ts

---

扩展思考模式

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  thinking: {
    type: 'enabled',
    budget_tokens: 2000,
  },
  messages: [{ role: 'user', content: 'Solve complex problem...' }],
});

const thinking = message.content.find(b => b.type === 'thinking')?.thinking;
const answer = message.content.find(b => b.type === 'text')?.text;

加载：templates/extended-thinking.ts

---

模型版本（当前）

最新模型：

• claude-sonnet-4-5-20250929 - 推荐（性能最佳）
• claude-sonnet-4-20250514 - 稳定版本
• claude-3-7-sonnet-20250219 - 上一代
• claude-3-5-sonnet-20241022 - 旧版

始终固定到特定版本（不要使用 -latest 后缀）

---

何时加载参考资料

在以下情况下加载 references/setup-guide.md：

• 首次使用 Claude API，需要完整的设置指南
• 从头开始设置 Node.js 或 Cloudflare Workers
• 需要生产环境部署清单和特定平台的技巧
• 排查基本设置问题（API 密钥、身份验证、环境）

在以下情况下加载 references/prompt-caching-guide.md：

• 希望将重复内容的成本降低 90%
• 在上下文中使用大型系统提示词、文档或代码库
• 需要包含基准测试和成本计算的详细缓存策略
• 通过缓存对话历史来优化多轮对话
• 排查缓存未启用或缓存未命中问题

在以下情况下加载 references/tool-use-patterns.md：

• 实现函数调用和工具定义
• 需要工具执行循环模式和多轮工具调用
• 希望了解用于类型安全工具的 Zod 验证示例
• 排查工具调用响应格式错误

在以下情况下加载 references/vision-capabilities.md：

• 使用 Claude 处理图像（OCR、分析、描述）
• 需要图像格式要求和验证逻辑
• 希望了解视觉功能的用例和最佳实践
• 将视觉功能与工具或提示词缓存结合使用

在以下情况下加载 references/api-reference.md：

• 需要完整的 API 参数参考和请求／响应架构
• 查找特定字段或内容块类型
• 需要端点详情、身份验证标头或模型 ID
• 需要了解流式事件类型和 SSE 格式详情

在以下情况下加载 references/top-errors.md：

• 遇到 API 错误（已记录的 12 种错误及其解决方案）
• 需要错误代码参考（400、401、429、529 等）
• 希望了解全面的预防策略
• 实现健壮的错误处理和重试逻辑

在以下情况下加载 references/rate-limits.md：

• 规划高流量使用和扩展策略
• 反复遇到 429 速率限制错误
• 需要了解各级别的限制和升级路径
• 优化请求模式，使其不超出限制

---

使用捆绑资源

参考文档（references/）

• setup-guide.md - 完整设置指南（Node.js + Cloudflare Workers + Next.js）
• api-reference.md - 完整的 API 参数参考和架构
• prompt-caching-guide.md - 节省 90% 成本的指南和基准测试
• tool-use-patterns.md - 函数调用模式和 Zod 示例
• vision-capabilities.md - 图像理解指南和验证
• top-errors.md - 全部 12 种错误及其解决方案和预防措施
• rate-limits.md - 各级别的限制和最佳实践

模板（templates/）

• basic-chat.ts - 简单聊天示例
• streaming-chat.ts - 使用 SSE 的流式实现
• prompt-caching.ts - 包含基准测试的缓存示例
• tool-use-basic.ts - 基本工具调用模式
• tool-use-advanced.ts - 高级多轮工具调用模式
• vision-image.ts - 包含验证的视觉功能示例
• extended-thinking.ts - 扩展思考模式
• error-handling.ts - 完整的错误处理
• nodejs-example.ts - 完整的 Node.js 应用
• cloudflare-worker.ts - 完整的 CF Worker
• nextjs-api-route.ts - Next.js API 路由
• package.json - 依赖项

---

平台集成

Node.js：bun add @anthropic-ai/sdk → 使用模板：nodejs-example.ts、basic-chat.ts

Cloudflare Workers：使用 fetch API → 使用模板：cloudflare-worker.ts

Next.js：bun add @anthropic-ai/sdk → 使用模板：nextjs-api-route.ts

---

生产环境检查清单

• 安全存储 API 密钥（环境变量）
• 实现错误处理（401、429、400、529）
• 使用指数退避进行速率限制
• 为重复内容启用提示词缓存
• 对较长的响应使用流式传输
• 输入验证 + 输出清理
• 监控和成本跟踪
• 配置超时
• 固定模型版本
• 适当设置 max_tokens

---

相关技能

• openai-api - 用于比较的 OpenAI Chat Completions
• claude-agent-sdk - 更高级的 Claude SDK
• ai-sdk-core - Vercel AI SDK（支持 Claude）

---

官方文档

• Messages API：https://docs.anthropic.com/en/api/messages
• 提示缓存：https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• 工具使用：https://docs.anthropic.com/en/docs/build-with-claude/tool-use
• 视觉：https://docs.anthropic.com/en/docs/build-with-claude/vision
• 扩展思考：https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking

---

有问题？遇到故障？

1. 查看 references/top-errors.md，了解错误解决方法
2. 查看 references/setup-guide.md，了解完整设置流程
3. 查看 references/prompt-caching-guide.md，了解成本优化方法
4. 从 templates/ 加载模板，查看可运行示例