参考数据：Claude API 参考 — TypeScript

Data: Claude API reference — TypeScript

v2.1.63

TypeScript SDK reference including installation, client initialization, basic requests, thinking, and multi-turn conversation

Claude API — TypeScript

安装

bash

npm install @anthropic-ai/sdk

客户端初始化

typescript

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

// 默认方式（使用 ANTHROPIC_API_KEY 环境变量）
const client = new Anthropic();

// 显式指定 API 密钥
const client = new Anthropic({ apiKey: "your-api-key" });

基础消息请求

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What is the capital of France?" }],
});
console.log(response.content[0].text);

系统提示词

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  system:
    "You are a helpful coding assistant. Always provide examples in Python.",
  messages: [{ role: "user", content: "How do I read a JSON file?" }],
});

视觉功能（图像）

URL

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: { type: "url", url: "https://example.com/image.png" },
        },
        { type: "text", text: "Describe this image" },
      ],
    },
  ],
});

Base64

typescript

import fs from "fs";

const imageData = fs.readFileSync("image.png").toString("base64");

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: { type: "base64", media_type: "image/png", data: imageData },
        },
        { type: "text", text: "What's in this image?" },
      ],
    },
  ],
});

提示词缓存

自动缓存（推荐）

使用顶层的 cache_control 自动缓存请求中最后一个可缓存的块：

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" }, // 自动缓存最后一个可缓存的块
  system: "You are an expert on this large document...",
  messages: [{ role: "user", content: "Summarize the key points" }],
});

手动缓存控制

如需精细控制，可为特定的内容块添加 cache_control：

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "You are an expert on this large document...",
      cache_control: { type: "ephemeral" }, // 默认 TTL 为 5 分钟
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points" }],
});

// 使用显式 TTL（生存时间）
const response2 = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "You are an expert on this large document...",
      cache_control: { type: "ephemeral", ttl: "1h" }, // 1 小时 TTL
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points" }],
});

扩展思考

Opus 4.6 和 Sonnet 4.6： 使用自适应思考。budget_tokens 在 Opus 4.6 和 Sonnet 4.6 上均已弃用。 旧模型： 使用 thinking: {type: "enabled", budget_tokens: N}（必须小于 max_tokens，最小为 1024）。

typescript

// Opus 4.6：自适应思考（推荐）
const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" }, // low | medium | high | max
  messages: [
    { role: "user", content: "Solve this math problem step by step..." },
  ],
});

for (const block of response.content) {
  if (block.type === "thinking") {
    console.log("Thinking:", block.thinking);
  } else if (block.type === "text") {
    console.log("Response:", block.text);
  }
}

错误处理

使用 SDK 的类型化异常类——切勿通过字符串匹配来检查错误消息：

typescript

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

try {
  const response = await client.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.BadRequestError) {
    console.error("Bad request:", error.message);
  } else if (error instanceof Anthropic.AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof Anthropic.RateLimitError) {
    console.error("Rate limited - retry later");
  } else if (error instanceof Anthropic.APIError) {
    console.error(`API error ${error.status}:`, error.message);
  }
}

所有类都继承自 Anthropic.APIError，并包含一个类型化的 status 字段。检查顺序应从最具体到最不具体。完整的错误代码参考请参见 shared/error-codes.md。

多轮对话

API 是无状态的——每次都需要发送完整的对话历史。使用 Anthropic.MessageParam[] 来为消息数组添加类型：

typescript

const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "My name is Alice." },
  { role: "assistant", content: "Hello Alice! Nice to meet you." },
  { role: "user", content: "What's my name?" },
];

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: messages,
});

规则：

消息必须在 user 和 assistant 之间交替
第一条消息必须是 user
对所有 API 数据结构使用 SDK 类型（Anthropic.MessageParam、Anthropic.Message、Anthropic.Tool 等）——不要重新定义等效的接口

压缩（长对话）

Beta 功能，仅限 Opus 4.6。 当对话接近 200K 上下文窗口时，压缩功能会自动在服务器端总结较早的上下文。API 会返回一个 compaction 块；你必须在后续请求中将其传回——追加 response.content，而不仅仅是文本。

typescript

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

const client = new Anthropic();
const messages: Anthropic.Beta.BetaMessageParam[] = [];

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

  const response = await client.beta.messages.create({
    betas: ["compact-2026-01-12"],
    model: "{\{OPUS_ID}\}",
    max_tokens: 4096,
    messages,
    context_management: {
      edits: [{ type: "compact_20260112" }],
    },
  });

  // 追加完整内容——压缩块必须保留
  messages.push({ role: "assistant", content: response.content });

  const textBlock = response.content.find((block) => block.type === "text");
  return textBlock?.text ?? "";
}

// 当上下文变得很大时，压缩会自动触发
console.log(await chat("Help me build a Python web scraper"));
console.log(await chat("Add support for JavaScript-rendered pages"));
console.log(await chat("Now add rate limiting and error handling"));

停止原因

响应中的 stop_reason 字段指示模型停止生成的原因：

值	含义
`end_turn`	Claude 自然完成了其响应
`max_tokens`	达到了 `max_tokens` 限制——请增加该值或使用流式传输
`stop_sequence`	遇到了自定义的停止序列
`tool_use`	Claude 想要调用一个工具——执行它并继续
`pause_turn`	模型暂停，可以恢复（智能体流程）
`refusal`	Claude 出于安全原因拒绝——输出可能不符合模式

成本优化策略

1. 对重复上下文使用提示词缓存

typescript

// 自动缓存（最简单——缓存最后一个可缓存的块）
const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" },
  system: largeDocumentText, // 例如，50KB 的上下文
  messages: [{ role: "user", content: "Summarize the key points" }],
});

// 第一次请求：完整成本
// 后续请求：缓存部分成本降低约 90%

2. 在请求前使用 Token 计数

typescript

const countResponse = await client.messages.countTokens({
  model: "{\{OPUS_ID}\}",
  messages: messages,
  system: system,
});

const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens
console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`);

英文原文 / English Original

Claude API — TypeScript

Installation

bash

npm install @anthropic-ai/sdk

Client Initialization

typescript

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

// Default (uses ANTHROPIC_API_KEY env var)
const client = new Anthropic();

// Explicit API key
const client = new Anthropic({ apiKey: "your-api-key" });

Basic Message Request

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What is the capital of France?" }],
});
console.log(response.content[0].text);

System Prompts

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  system:
    "You are a helpful coding assistant. Always provide examples in Python.",
  messages: [{ role: "user", content: "How do I read a JSON file?" }],
});

Vision (Images)

URL

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: { type: "url", url: "https://example.com/image.png" },
        },
        { type: "text", text: "Describe this image" },
      ],
    },
  ],
});

Base64

typescript

import fs from "fs";

const imageData = fs.readFileSync("image.png").toString("base64");

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: { type: "base64", media_type: "image/png", data: imageData },
        },
        { type: "text", text: "What's in this image?" },
      ],
    },
  ],
});

Prompt Caching

Automatic Caching (Recommended)

Use top-level cache_control to automatically cache the last cacheable block in the request:

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block
  system: "You are an expert on this large document...",
  messages: [{ role: "user", content: "Summarize the key points" }],
});

Manual Cache Control

For fine-grained control, add cache_control to specific content blocks:

typescript

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "You are an expert on this large document...",
      cache_control: { type: "ephemeral" }, // default TTL is 5 minutes
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points" }],
});

// With explicit TTL (time-to-live)
const response2 = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "You are an expert on this large document...",
      cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points" }],
});

Extended Thinking

Opus 4.6 and Sonnet 4.6: Use adaptive thinking. budget_tokens is deprecated on both Opus 4.6 and Sonnet 4.6. Older models: Use thinking: {type: "enabled", budget_tokens: N} (must be < max_tokens, min 1024).

typescript

// Opus 4.6: adaptive thinking (recommended)
const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" }, // low | medium | high | max
  messages: [
    { role: "user", content: "Solve this math problem step by step..." },
  ],
});

for (const block of response.content) {
  if (block.type === "thinking") {
    console.log("Thinking:", block.thinking);
  } else if (block.type === "text") {
    console.log("Response:", block.text);
  }
}

Error Handling

Use the SDK's typed exception classes — never check error messages with string matching:

typescript

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

try {
  const response = await client.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.BadRequestError) {
    console.error("Bad request:", error.message);
  } else if (error instanceof Anthropic.AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof Anthropic.RateLimitError) {
    console.error("Rate limited - retry later");
  } else if (error instanceof Anthropic.APIError) {
    console.error(`API error \${error.status}:`, error.message);
  }
}

All classes extend Anthropic.APIError with a typed status field. Check from most specific to least specific. See shared/error-codes.md for the full error code reference.

Multi-Turn Conversations

The API is stateless — send the full conversation history each time. Use Anthropic.MessageParam[] to type the messages array:

typescript

const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "My name is Alice." },
  { role: "assistant", content: "Hello Alice! Nice to meet you." },
  { role: "user", content: "What's my name?" },
];

const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  messages: messages,
});

Rules:

Messages must alternate between user and assistant
First message must be user
Use SDK types (Anthropic.MessageParam, Anthropic.Message, Anthropic.Tool, etc.) for all API data structures — don't redefine equivalent interfaces

Compaction (long conversations)

Beta, Opus 4.6 only. When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a compaction block; you must pass it back on subsequent requests — append response.content, not just the text.

typescript

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

const client = new Anthropic();
const messages: Anthropic.Beta.BetaMessageParam[] = [];

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

  const response = await client.beta.messages.create({
    betas: ["compact-2026-01-12"],
    model: "{\{OPUS_ID}\}",
    max_tokens: 4096,
    messages,
    context_management: {
      edits: [{ type: "compact_20260112" }],
    },
  });

  // Append full content — compaction blocks must be preserved
  messages.push({ role: "assistant", content: response.content });

  const textBlock = response.content.find((block) => block.type === "text");
  return textBlock?.text ?? "";
}

// Compaction triggers automatically when context grows large
console.log(await chat("Help me build a Python web scraper"));
console.log(await chat("Add support for JavaScript-rendered pages"));
console.log(await chat("Now add rate limiting and error handling"));

Stop Reasons

The stop_reason field in the response indicates why the model stopped generating:

Value	Meaning
`end_turn`	Claude finished its response naturally
`max_tokens`	Hit the `max_tokens` limit — increase it or use streaming
`stop_sequence`	Hit a custom stop sequence
`tool_use`	Claude wants to call a tool — execute it and continue
`pause_turn`	Model paused and can be resumed (agentic flows)
`refusal`	Claude refused for safety reasons — output may not match schema

Cost Optimization Strategies

1. Use Prompt Caching for Repeated Context

typescript

// Automatic caching (simplest — caches the last cacheable block)
const response = await client.messages.create({
  model: "{\{OPUS_ID}\}",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" },
  system: largeDocumentText, // e.g., 50KB of context
  messages: [{ role: "user", content: "Summarize the key points" }],
});

// First request: full cost
// Subsequent requests: ~90% cheaper for cached portion

2. Use Token Counting Before Requests

typescript

const countResponse = await client.messages.countTokens({
  model: "{\{OPUS_ID}\}",
  messages: messages,
  system: system,
});

const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens
console.log(`Estimated input cost: $\${estimatedInputCost.toFixed(4)}`);

参考数据：Claude API 参考 — TypeScript ​

Claude API — TypeScript ​

安装 ​

客户端初始化 ​

基础消息请求 ​

系统提示词 ​

视觉功能（图像） ​

URL ​

Base64 ​

提示词缓存 ​

自动缓存（推荐） ​

手动缓存控制 ​

扩展思考 ​

错误处理 ​

多轮对话 ​

压缩（长对话） ​

停止原因 ​

成本优化策略 ​

1. 对重复上下文使用提示词缓存 ​

2. 在请求前使用 Token 计数 ​

Claude API — TypeScript ​

Installation ​

Client Initialization ​

Basic Message Request ​

System Prompts ​

Vision (Images) ​

URL ​

Base64 ​

Prompt Caching ​

Automatic Caching (Recommended) ​

Manual Cache Control ​

Extended Thinking ​

Error Handling ​

Multi-Turn Conversations ​

Compaction (long conversations) ​

Stop Reasons ​

Cost Optimization Strategies ​

1. Use Prompt Caching for Repeated Context ​

2. Use Token Counting Before Requests ​

参考数据：Claude API 参考 — TypeScript

Claude API — TypeScript

安装

客户端初始化

基础消息请求

系统提示词

视觉功能（图像）

URL

Base64

提示词缓存

自动缓存（推荐）

手动缓存控制

扩展思考

错误处理

多轮对话

压缩（长对话）

停止原因

成本优化策略

1. 对重复上下文使用提示词缓存

2. 在请求前使用 Token 计数

Claude API — TypeScript

Installation

Client Initialization

Basic Message Request

System Prompts

Vision (Images)

URL

Base64

Prompt Caching

Automatic Caching (Recommended)

Manual Cache Control

Extended Thinking

Error Handling

Multi-Turn Conversations

Compaction (long conversations)

Stop Reasons

Cost Optimization Strategies

1. Use Prompt Caching for Repeated Context

2. Use Token Counting Before Requests