Claude学院

Claude API Node.js 调用示例：从安装到流式输出

用 Node.js 调用 Claude API 只需三步：执行 npm install @anthropic-ai/sdk 安装官方 SDK，把 API Key 写进环境变量 ANTHROPIC_API_KEY，然后调用 client.messages.create() 发请求。要做打字机效果的流式输出，把 create 换成 stream 即可。下面给出从零到流式输出的完整可运行代码。

第一步：环境准备与安装

Node.js 需要 18 或更高版本（SDK 依赖内置的 fetch 与 Web Streams）。新建项目并安装官方 SDK：

mkdir claude-demo && cd claude-demo
npm init -y
npm install @anthropic-ai/sdk

包名是 @anthropic-ai/sdk，注意不要装成第三方的同名仿冒包。如果还没有密钥，先看这篇申请流程把 Key 拿到手；对接口整体不熟的话，建议先读从注册到第一次请求完整教程打个底。

第二步：配置 API Key

不要把密钥硬编码进代码。Claude 的鉴权方式是请求头里带 x-api-key 和 anthropic-version，但用 SDK 时这些都自动处理，你只要把密钥放进环境变量：

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-你的密钥"

# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-ant-你的密钥"

SDK 默认从 process.env.ANTHROPIC_API_KEY 读取，无需在代码里显式传参。如果一定要传，可以写 new Anthropic({ apiKey: '...' })。

第三步：发起第一次请求

新建 index.mjs（用 .mjs 或在 package.json 里设 "type": "module" 以启用 ESM）：

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

const client = new Anthropic(); // 自动读取 ANTHROPIC_API_KEY

const message = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: '用一句话介绍 Node.js 是什么。' },
  ],
});

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

运行 node index.mjs，几秒后就能看到回复。这里调用的是 Messages API（POST /v1/messages），它是 Claude 当前唯一的对话接口。几个关键参数：

  • model：模型 ID。当前主力是 claude-opus-4-8（最强）、claude-sonnet-4-6（速度与智能均衡）、claude-haiku-4-5（最快最省）。怎么选可参考模型选型指南。
  • max_tokens：本次回复的最大 token 数，必填。非流式建议 16000 以内，避免超过 SDK 的 HTTP 超时；流式可放到 64000。
  • messages：对话数组，每条带 role（user 或 assistant）和 content。首条必须是 user，且 user / assistant 必须交替。

返回的 message.content 是一个内容块数组，文本在 content[0].text。Token 用量在 message.usage 里，计费按它统计，具体价格以 Anthropic 官网为准。

流式输出：实现逐字返回

一次性等完整回复在长文本下体验很差。Claude 通过 SSE（Server-Sent Events）支持流式输出，让内容像 ChatGPT 那样逐字蹦出来。SDK 把 SSE 解析封装好了，用 client.messages.stream() 监听 text 事件即可：

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

const client = new Anthropic();

const stream = client.messages.stream({
  model: 'claude-opus-4-8',
  max_tokens: 4096,
  messages: [
    { role: 'user', content: '写一首关于编程的短诗。' },
  ],
});

// 逐个增量片段打印，process.stdout.write 不换行
stream.on('text', (delta) => {
  process.stdout.write(delta);
});

// 等流结束，拿到拼好的完整 Message 对象
const finalMessage = await stream.finalMessage();
console.log('\n\n用量：', finalMessage.usage);

底层每个事件对应一个 SSE 帧：message_start 开头、content_block_delta 携带文本增量、message_stop 结束。SDK 的 text 事件直接给你解析好的增量字符串，省去手动处理这些帧。

如果你只想拿最终结果、不需要逐帧处理，可以直接 await stream.finalMessage()，不必自己用 new Promise 包事件回调。Python 版的同等实现可对照流式输出 Python 教程，原理一致。

用 fetch 直接调原始接口（不依赖 SDK）

个别场景（边缘函数、想完全控制请求）你可能不想引 SDK。Node 18+ 自带 fetch，可直接打 Messages API，这时鉴权头要自己写：

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

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

注意两个必填头：x-api-key 是密钥，anthropic-version 是 API 版本（写 2023-06-01）。多数情况仍推荐用 SDK，它帮你处理了重试、流式解析和类型。

进阶：工具调用与多轮对话

SDK 支持 Tool Use（工具调用），让模型调用你定义的函数。基本流程是：在 tools 里声明函数 schema，模型返回 tool_use 块，你执行后把结果以 tool_result 回传。完整写法见Tool Use 完整代码实战。多轮对话则是把每轮的 user 和 assistant 消息按顺序追加进 messages 数组，参考上下文管理详解。

另外两个实用点：thinking: { type: 'adaptive' } 可开启自适应思考，让模型在复杂任务上自行决定推理深度；output_config: { effort: 'high' } 控制投入程度。这些都是当前 Opus 4.8 的推荐用法。

常见问题

报 401 认证失败怎么办？

多半是 ANTHROPIC_API_KEY 没设置成功、密钥拼错或已失效。先在终端执行 echo $ANTHROPIC_API_KEY 确认变量真的有值，再检查密钥是否被吊销。详细排查见401 认证失败排查指南。

遇到 429 限流报错如何处理？

429 表示触发了速率限制（RPM 或 TPM）。SDK 默认会对 429 和 5xx 做指数退避重试（maxRetries 默认 2 次），你也可以读响应头 retry-after 自行控制节奏。更多方案见429 限流的 3 种重试方案。

max_tokens 设多大合适？

它是单次回复的硬上限，设小了会被中途截断需要重试。非流式请求建议 16000 以内以避开 HTTP 超时；流式请求没有超时顾虑，可设到 64000。简单分类任务给几百即可，长文生成才需要往上调。token 怎么估算见Token 计算与在线估算方法。

← Claude API 开发