Anthropic Node.js SDK 完全指南：TypeScript/JavaScript 接入 Claude API

npm install @anthropic-ai/sdk
# 或
pnpm add @anthropic-ai/sdk

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

// 自动读取 ANTHROPIC_API_KEY 环境变量
const client = new Anthropic();

// 或显式传入
const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxRetries: 3,       // 自动重试次数（默认 2）
  timeout: 60_000,     // 请求超时（ms，默认 10 分钟）
});

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "帮我写一个 TypeScript 的防抖函数" }
  ],
});

// 提取文本回复
const text = message.content[0].type === "text"
  ? message.content[0].text
  : "";
console.log(text);

// 查看 Token 用量
console.log("输入:", message.usage.input_tokens);
console.log("输出:", message.usage.output_tokens);

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 2048,
  system: "你是一位资深 TypeScript 工程师，回答问题时提供完整可运行的代码示例。",
  messages: [
    { role: "user", content: "如何实现一个类型安全的事件总线？" }
  ],
});

// 方式一：stream helper（推荐）
const stream = await client.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  messages: [{ role: "user", content: "写一篇关于 TypeScript 泛型的完整教程" }],
});

// 实时打印
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.getFinalMessage();
console.log("
总 Token：", finalMessage.usage);

// 方式二：原始 SSE 事件
const stream2 = client.messages.stream({...});
stream2.on("text", (text) => process.stdout.write(text));
await stream2.finalMessage();

const history: Anthropic.MessageParam[] = [];

async function chat(userMessage: string): Promise<string> {
  history.push({ role: "user", content: userMessage });

  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    messages: history,
  });

  const assistantMessage = response.content[0].type === "text"
    ? response.content[0].text : "";

  history.push({ role: "assistant", content: assistantMessage });
  return assistantMessage;
}

// 使用
await chat("你好，我是 Alice");
await chat("我刚才说我叫什么？");  // Claude 会记住 "Alice"

import * as fs from "fs";

// Base64 图像
const imageData = fs.readFileSync("screenshot.png").toString("base64");

const message = await 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: imageData,
        },
      },
      { type: "text", text: "这张截图里的代码有什么问题？" },
    ],
  }],
});

// URL 图像
const message2 = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: [
      {
        type: "image",
        source: { type: "url", url: "https://example.com/diagram.png" },
      },
      { type: "text", text: "解释这个架构图" },
    ],
  }],
});

const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description: "获取指定城市的当前天气",
    input_schema: {
      type: "object" as const,
      properties: {
        city: { type: "string", description: "城市名称，如'北京'、'上海'" },
        unit: { type: "string", enum: ["celsius", "fahrenheit"] },
      },
      required: ["city"],
    },
  },
];

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  tools,
  messages: [{ role: "user", content: "上海今天天气怎么样？" }],
});

// 处理工具调用
if (response.stop_reason === "tool_use") {
  for (const block of response.content) {
    if (block.type === "tool_use") {
      console.log("调用工具:", block.name);
      console.log("参数:", block.input);
      // block.input.city === "上海"
    }
  }
}

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "你是一位专业的代码审查专家...",  // 长系统提示
      cache_control: { type: "ephemeral" },  // 标记为可缓存
    },
  ],
  messages: [{ role: "user", content: userInput }],
});
// 缓存命中时输入 Token 费用降低 90%

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

async function safeCall(prompt: string) {
  try {
    return await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      messages: [{ role: "user", content: prompt }],
    });
  } catch (error) {
    if (error instanceof Anthropic.AuthenticationError) {
      // 401：API Key 无效
      throw new Error("API Key 配置错误");
    } else if (error instanceof Anthropic.RateLimitError) {
      // 429：速率限制（SDK 默认会自动重试）
      throw new Error("触发速率限制，请稍后重试");
    } else if (error instanceof Anthropic.APIError) {
      console.error(`API 错误 ${error.status}: ${error.message}`);
      throw error;
    }
    throw error;
  }
}