name: claude-api description: Anthropic Messages API (Claude API) 用于集成、流式传输、提示缓存、工具使用、视觉。用于聊天机器人、助手，或遇到速率限制、429错误。

关键词：claude api, anthropic api, messages api, @anthropic-ai/sdk, claude streaming, prompt caching, tool use, vision, extended thinking, claude 3.5 sonnet, claude 3.7 sonnet, claude sonnet 4, function calling, SSE, rate limits, 429 errors license: MIT metadata: version: “2.0.0” last_verified: “2025-11-21” sdk_version: “@anthropic-ai/sdk@0.70.1” templates_included: 12 references_included: 7

Claude API (Anthropic Messages API)

状态: 生产就绪 | SDK: @anthropic-ai/sdk@0.70.1

快速开始 (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 以获取流式传输、缓存和工具的完整设置。

关键规则

始终做 ✅

使用环境变量 存储 API 密钥（绝不硬编码）
设置 max_tokens 明确（必需参数）
固定模型版本 (claude-sonnet-4-5-20250929，而不是 claude-3-5-sonnet-latest)
启用提示缓存 用于重复内容（节省 90% 成本）
流式长响应 (stream: true) 以获得更好的用户体验
处理错误 - 实现重试逻辑处理 429、529 错误
验证输入 - 在发送前清理用户消息
监控成本 - 跟踪令牌使用
设置超时 - 防止请求挂起
正确使用工具 - 在后续消息中返回 tool_result

绝不做 ❌

绝不暴露 API 密钥 在客户端代码中
绝不跳过 max_tokens - API 将出错
绝不错过 stop_reason - 检查 tool_use、end_turn、max_tokens
绝不假设单一内容块 - content 是数组
绝不使用过时模型 - 固定到特定版本
绝不忽略错误处理 - API 调用可能失败
绝不混合消息角色 - 正确交替用户/助手
绝不忽略速率限制 - 实现指数退避
绝不存储 API 密钥 在日志或数据库中
绝不跳过输入验证 - 防止注入攻击

前 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 令牌

// ❌ 错误 - cache_control 不在末尾
{
  type: 'text',
  text: DOCUMENT,
  cache_control: { type: 'ephemeral' },  // 错误位置
},
{
  type: 'text',
  text: 'Additional text',
}

// ✅ 正确 - cache_control 在末尾
{
  type: 'text',
  text: DOCUMENT + '

Additional text',
  cache_control: { type: 'ephemeral' },  // 正确位置
}

预防: 确保内容 >= 1024 令牌，保持缓存内容相同，监控使用

加载 references/prompt-caching-guide.md 以获取完整缓存策略。

错误 #3: 工具使用响应格式错误

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

解决方案: 使用正确 JSON Schema 的有效工具模式

// ✅ 有效工具模式
{
  name: 'get_weather',
  description: '获取当前天气',
  input_schema: {
    type: 'object',           // 必须是 'object'
    properties: {
      location: {
        type: 'string',       // 有效的 JSON Schema 类型
        description: '城市'   // 可选但推荐
      }
    },
    required: ['location']    // 列出必需字段
  }
}

// ✅ 有效工具结果
{
  type: 'tool_result',
  tool_use_id: block.id,      // 必须匹配 tool_use id
  content: JSON.stringify(result)  // 转换为字符串
}

预防: 验证模式，精确匹配 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: '写一个故事。' }],
});

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: '长系统提示...',
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [{ role: 'user', content: '问题？' }],
});

缓存持续 5 分钟，节省 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: '获取某个位置的天气',
    input_schema: {
      type: 'object',
      properties: { location: { type: 'string' } },
      required: ['location'],
    },
  }],
  messages: [{ role: 'user', content: '旧金山天气？' }],
});

if (message.stop_reason === 'tool_use') {
  const toolUse = message.content.find(b => b.type === 'tool_use');
  // 执行工具并发送结果回...
}

加载: 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: '这张图片里有什么？' },
    ],
  }],
});

支持: JPEG, PNG, WebP, GIF (最大 5MB)

加载: 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: '解决复杂问题...' }],
});

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 适当设置

官方文档

Messages API: https://docs.anthropic.com/en/api/messages
Prompt Caching: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
Tool Use: https://docs.anthropic.com/en/docs/build-with-claude/tool-use
Vision: https://docs.anthropic.com/en/docs/build-with-claude/vision
Extended Thinking: https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking

有问题？有疑问？

检查 references/top-errors.md 以获取错误解决方案
复习 references/setup-guide.md 以获取完整设置
查看 references/prompt-caching-guide.md 以获取成本优化
从 templates/ 加载模板以获取工作示例

ClaudeAPI集成开发 claude-api

Claude API (Anthropic Messages API)

快速开始 (5 分钟)

Node.js

Cloudflare Workers

关键规则

始终做 ✅

绝不做 ❌

前 3 个错误（预防 80% 的问题）

错误 #1: 速率限制 429

错误 #2: 提示缓存未激活

错误 #3: 工具使用响应格式错误

常见用例（快速模式）

流式响应

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

工具使用（函数调用）

视觉（图像理解）

扩展思考模式

模型版本（当前）

何时加载参考

加载 `references/setup-guide.md` 当:

加载 `references/prompt-caching-guide.md` 当:

加载 `references/tool-use-patterns.md` 当:

加载 `references/vision-capabilities.md` 当:

加载 `references/api-reference.md` 当:

加载 `references/top-errors.md` 当:

加载 `references/rate-limits.md` 当:

使用捆绑资源

参考 (references/)

模板 (templates/)

平台集成

生产清单

相关技能

官方文档

Claude API (Anthropic Messages API)

快速开始 (5 分钟)

Node.js

Cloudflare Workers

关键规则

始终做 ✅

绝不做 ❌

前 3 个错误（预防 80% 的问题）

错误 #1: 速率限制 429

错误 #2: 提示缓存未激活

错误 #3: 工具使用响应格式错误

常见用例（快速模式）

流式响应

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

工具使用（函数调用）

视觉（图像理解）

扩展思考模式

模型版本（当前）

何时加载参考

加载 references/setup-guide.md 当:

加载 references/prompt-caching-guide.md 当:

加载 references/tool-use-patterns.md 当:

加载 references/vision-capabilities.md 当:

加载 references/api-reference.md 当:

加载 references/top-errors.md 当:

加载 references/rate-limits.md 当:

使用捆绑资源

参考 (references/)

模板 (templates/)

平台集成

生产清单

相关技能

官方文档

加载 `references/setup-guide.md` 当:

加载 `references/prompt-caching-guide.md` 当:

加载 `references/tool-use-patterns.md` 当:

加载 `references/vision-capabilities.md` 当:

加载 `references/api-reference.md` 当:

加载 `references/top-errors.md` 当:

加载 `references/rate-limits.md` 当: