Claude API 怎么接入 Next.js？Messages API、system、流式和报错处理

Anthropic 的 Claude API 接入逻辑和别的 LLM 一样：key 放服务端、用 Route Handler 中转、前端只调你自己的接口。但 Messages API 有两个新手最容易踩的点：max_tokens 是必填的，system 是顶层参数、不是一条 message。

第一步：装 SDK + 配 Key

npm install @anthropic-ai/sdk

.env.local（不加 NEXT_PUBLIC_）：

ANTHROPIC_API_KEY=sk-ant-xxxxx

第二步：服务端 Route Handler（注意两个坑）

新建 app/api/claude/route.ts：

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

export const runtime = "nodejs";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

export async function POST(req: Request) {
  const { messages } = await req.json();
  const msg = await client.messages.create({
    model: "claude-sonnet-4-5",     // 以 Anthropic 官方当前模型为准
    max_tokens: 1024,               // 必填,漏了会直接报错
    system: "你是一个简洁的中文助手", // system 是顶层参数,不是 messages 里的一条
    messages,                       // 形如 [{ role: "user", content: "..." }]
  });
  return Response.json({ reply: msg.content });
}

两个高频报错就来自这里：漏 max_tokens、或把 system 当成 { role: "system" } 塞进 messages（Messages API 不接受 system 角色）。

第三步：流式返回

const stream = client.messages.stream({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages,
});
const encoder = new TextEncoder();
return new Response(new ReadableStream({
  async start(controller) {
    for await (const event of stream) {
      if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
        controller.enqueue(encoder.encode(event.delta.text));
      }
    }
    controller.close();
  },
}), { headers: { "Content-Type": "text/plain; charset=utf-8" } });

常见报错和修复

• 缺 max_tokens 报错：Messages API 必须传 max_tokens，补上即可。
• system 放错位置：别在 messages 里放 { role: "system" }，用顶层 system 字段。
• 401 authentication_error：key 错或没读到 → 检查 .env.local、重启 dev。
• 429 / overloaded_error：限流或服务繁忙 → 加指数退避重试；overloaded 通常稍后重试即可。
• 生产读不到：Vercel 没配 ANTHROPIC_API_KEY → 补环境变量并重新部署。

和 OpenAI 接入的主要差异

结构相近（key + 服务端 + 流式），差别在：SDK 是 @anthropic-ai/sdk、方法是 messages.create、max_tokens 必填、system 单独传、流式事件是 content_block_delta。换供应商主要改这层。

让 Codex 辅助

我在 Next.js 接 Claude（Anthropic）API 报 [贴报错]。
请判断是 max_tokens、system 位置、key、还是限流问题，给出修复，
并确认我的 key 没暴露在前端。

风险提醒

• key 只在服务端，泄露立刻在 Anthropic 后台吊销换新。
• 给 /api/claude 加频率限制和用量上限，别被人白嫖额度。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关 AI 接入

接其他模型 / 管好 key 一起看：

• OpenAI API 接入 Next.js 怎么做
• Gemini API 怎么接 Next.js
• AI API Key 怎么安全管理

免责声明

本文 SDK 用法与 Messages API 形态对应 Anthropic 与 Next.js 的通用行为；具体模型名、价格、限额以 Anthropic 官方文档为准，涉及客户密钥与账单时需明确授权并人工复核。