Claude API接口调用教程｜附完整命令

随着大语言模型在内容创作、代码生成、数据分析、智能客服、知识库问答等场景中的广泛应用，越来越多开发者开始关注如何将模型能力接入自己的业务系统。Claude 是 Anthropic 推出的大语言模型系列，具有较强的长文本理解、复杂推理、代码辅助和多轮对话能力。对于开发者而言，最直接的接入方式就是调用 Claude API。

本文将以中文教程的形式，系统讲解 Claude API 的调用流程，包括 API Key 获取、接口地址、请求参数、curl 命令示例、Python 调用示例、Node.js 调用示例、多轮对话写法、流式输出方式，以及常见报错排查。读完本文后，你可以直接复制命令进行测试，并进一步集成到自己的项目中。

一、Claude API 是什么？

Claude API 是 Anthropic 提供的模型接口服务。开发者可以通过 HTTP 请求，把用户输入的内容发送给 Claude 模型，然后获得模型生成的回复。

简单来说，Claude API 的调用流程如下：

1. 注册并进入 Anthropic 控制台；
2. 创建 API Key；
3. 选择要调用的 Claude 模型；
4. 按照接口规范构造请求；
5. 发送请求并接收模型返回结果；
6. 将结果展示在网站、应用或业务系统中。

Claude API 通常适用于以下场景：

• AI 聊天机器人；
• 智能客服系统；
• 文档总结与改写；
• 长文本分析；
• 代码生成与解释；
• 数据处理与结构化抽取；
• 企业知识库问答；
• 自动邮件、报告、文案生成；
• 工作流自动化工具。

二、调用 Claude API 前需要准备什么？

在正式调用之前，你需要准备以下内容。

1. Anthropic 账号

你需要拥有 Anthropic 账号，并进入官方控制台创建 API Key。

Anthropic 控制台地址通常为：

https://console.anthropic.com/

进入控制台后，找到 API Keys 或类似入口，创建一个新的密钥。

2. API Key

API Key 是调用 Claude API 的身份凭证。请求接口时，需要在 Header 中携带该密钥。

示例格式如下：

sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxx

注意：
API Key 非常敏感，不要提交到 GitHub、前端代码、公开文档或日志中。推荐使用环境变量保存。

例如在 Linux/macOS 终端中设置：

export ANTHROPIC_API_KEY="你的_API_Key"

Windows PowerShell 中可以这样设置：

$env:ANTHROPIC_API_KEY="你的_API_Key"

3. 选择 Claude 模型

Anthropic 会提供多个 Claude 模型版本。不同模型在推理能力、速度、成本、上下文长度方面可能不同。

常见模型名称示例：

claude-3-5-sonnet-latest
claude-3-5-haiku-latest
claude-3-opus-latest

实际可用模型请以 Anthropic 官方文档和控制台为准。

一般来说：

• 如果追求综合能力，可以选择 Sonnet 系列；
• 如果追求速度和成本，可以选择 Haiku 系列；
• 如果需要更强复杂推理能力，可以关注 Opus 系列。

三、Claude API 基础接口说明

Claude API 常用的消息接口为：

POST https://api.anthropic.com/v1/messages

请求时通常需要包含以下 Header：

Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

不过在 Anthropic 的官方调用方式中，常见写法是使用：

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

因此，本文主要使用 x-api-key 的方式进行演示。

四、Claude API 请求参数说明

一个基础请求体通常如下：

{
  "model": "claude-3-5-sonnet-latest",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "请用中文介绍一下Claude API。"
    }
  ]
}

主要参数说明如下。

其中，messages 是最核心的字段。Claude 会根据消息上下文生成回复。

五、使用 curl 调用 Claude API

下面是最基础的 curl 调用命令。你可以直接复制到终端执行。

1. 基础调用命令

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "请用中文写一段关于人工智能发展的简介。"
      }
    ]
  }'

如果你的环境变量配置正确，命令执行后会返回类似 JSON 数据：

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-3-5-sonnet-latest",
  "content": [
    {
      "type": "text",
      "text": "人工智能是计算机科学的重要分支..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 300
  }
}

其中，真正的模型回复通常位于：

content[0].text

2. 带 system 提示词的调用

system 字段用于设定模型的角色、风格和规则。例如你希望 Claude 扮演一名资深技术文档工程师，可以这样写：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 1500,
    "system": "你是一名资深技术文档工程师，擅长用清晰、准确、结构化的中文解释复杂技术。",
    "messages": [
      {
        "role": "user",
        "content": "请解释什么是RESTful API，并给出一个简单例子。"
      }
    ]
  }'

system 提示词适合放置长期规则，例如：

• 模型身份；
• 输出语言；
• 输出格式；
• 安全边界；
• 回答风格；
• 业务规则；
• 禁止事项。

3. 设置 temperature

如果你希望模型回答更加稳定，可以降低 temperature；如果希望更有创意，可以提高该值。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 1200,
    "temperature": 0.3,
    "messages": [
      {
        "role": "user",
        "content": "请生成一份适合初学者的Python学习计划。"
      }
    ]
  }'

一般建议：

• 代码生成、数据抽取、技术问答：temperature 可设置为 0 到 0.3；
• 文案创作、头脑风暴、故事生成：temperature 可设置为 0.7 到 1；
• 严肃业务场景：尽量降低随机性。

六、Claude API 多轮对话调用

Claude API 本身不会自动记住之前的对话。所谓“上下文记忆”，通常是开发者把历史消息一起传给接口。

例如：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 1000,
    "messages": [
      {
        "role": "user",
        "content": "你能帮我制定一个健身计划吗？"
      },
      {
        "role": "assistant",
        "content": "当然可以。请告诉我你的目标、每周可训练时间和目前身体情况。"
      },
      {
        "role": "user",
        "content": "我的目标是减脂，每周训练4次，没有明显伤病。"
      }
    ]
  }'

在实际项目中，多轮对话通常需要后端保存历史消息，例如保存到：

• Redis；
• MySQL；
• PostgreSQL；
• MongoDB；
• 本地缓存；
• 会话状态管理系统。

需要注意的是，上下文越长，消耗的 token 越多，成本也会增加。因此需要合理控制历史消息长度。常见做法包括：

1. 只保留最近若干轮对话；
2. 对旧对话进行摘要；
3. 只保留关键事实；
4. 根据业务场景构造短上下文；
5. 使用向量数据库召回相关内容，而不是传入全部历史。

七、Python 调用 Claude API 示例

如果你正在开发 Python 项目，可以使用官方 SDK 或直接使用 requests 调用。下面分别演示。

1. 安装 Anthropic Python SDK

pip install anthropic

2. Python SDK 基础调用

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)

message = client.messages.create(
    model="claude-3-5-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "请用中文解释什么是API。"
        }
    ]
)

print(message.content[0].text)

运行命令：

python app.py

3. Python SDK 带 system 调用

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

response = client.messages.create(
    model="claude-3-5-sonnet-latest",
    max_tokens=1500,
    system="你是一名专业的软件架构师，请用简洁、准确、结构化的中文回答问题。",
    messages=[
        {
            "role": "user",
            "content": "请说明微服务架构的优点和缺点。"
        }
    ]
)

print(response.content[0].text)

4. 使用 requests 直接调用

如果你不想安装官方 SDK，也可以使用 requests：

pip install requests

Python 代码如下：

import os
import requests

api_key = os.getenv("ANTHROPIC_API_KEY")

url = "https://api.anthropic.com/v1/messages"

headers = {
    "x-api-key": api_key,
    "anthropic-version": "2023-06-01",
    "Content-Type": "application/json"
}

payload = {
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": "请写一个Python函数，用于判断字符串是否为回文。"
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)

print(response.status_code)
print(response.json())

如果只想打印模型文本，可以这样写：

data = response.json()
print(data["content"][0]["text"])

八、Node.js 调用 Claude API 示例

Node.js 项目也可以通过官方 SDK 调用 Claude API。

1. 初始化项目

mkdir claude-api-demo
cd claude-api-demo
npm init -y

2. 安装 Anthropic SDK

npm install @anthropic-ai/sdk

3. Node.js 基础调用

创建 index.js：

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

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function main() {
  const message = await anthropic.messages.create({
    model: "claude-3-5-sonnet-latest",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "请用中文解释什么是HTTP协议。",
      },
    ],
  });

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

main();

由于使用了 import，需要在 package.json 中加入：

{
  "type": "module"
}

运行：

node index.js

4. Node.js 使用 fetch 直接调用

如果你不想使用 SDK，也可以使用原生 fetch：

const response = 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-3-5-sonnet-latest",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "请生成一个JavaScript防抖函数，并解释其原理。",
      },
    ],
  }),
});

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

如果你的 Node.js 版本较旧，不支持全局 fetch，可以安装 node-fetch。

九、Claude API 流式输出调用

在聊天机器人、网页对话、代码生成器等场景中，用户通常不希望等到全部内容生成完才看到结果。此时可以使用流式输出。

流式输出的核心是设置：

"stream": true

1. curl 流式输出示例

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "请用中文写一篇关于云计算优势的短文。"
      }
    ]
  }'

流式输出会返回一系列事件，例如：

event: message_start
event: content_block_start
event: content_block_delta
event: content_block_stop
event: message_stop

真正增量文本通常位于 content_block_delta 事件中。

2. Python SDK 流式输出示例

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

with client.messages.stream(
    model="claude-3-5-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "请用中文讲解一下Docker的核心概念。"
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

这种方式适合命令行工具、实时聊天界面和在线编辑器。

十、如何让 Claude 返回 JSON 格式？

在业务开发中，我们经常希望模型返回结构化数据，例如分类结果、摘要字段、实体识别结果等。此时可以通过明确提示词要求模型输出 JSON。

示例：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 800,
    "system": "你是一个信息抽取助手。必须只返回合法JSON，不要输出Markdown，不要添加解释。",
    "messages": [
      {
        "role": "user",
        "content": "请从下面文本中抽取姓名、公司和职位：张三目前在星河科技担任产品经理。"
      }
    ]
  }'

理想返回：

{
  "name": "张三",
  "company": "星河科技",
  "position": "产品经理"
}

为了提高 JSON 稳定性，建议：

1. 在 system 中明确要求“只返回合法 JSON”；
2. 给出字段名和字段类型；
3. 不要让模型同时输出解释和 JSON；
4. 后端使用 JSON 解析器校验；
5. 解析失败时进行重试或修复。

十一、常见错误与解决方法

1. 401 Unauthorized

常见原因：

• API Key 错误；
• 没有设置环境变量；
• Header 中没有携带 x-api-key；
• API Key 被删除或失效。

解决方法：

echo $ANTHROPIC_API_KEY

确认环境变量存在。如果为空，重新设置：

export ANTHROPIC_API_KEY="你的_API_Key"

2. 400 Bad Request

常见原因：

• JSON 格式错误；
• 模型名称写错；
• 缺少必填字段；
• messages 格式不正确；
• max_tokens 未填写。

建议检查请求体，例如：

{
  "model": "claude-3-5-sonnet-latest",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "测试"
    }
  ]
}

3. 429 Too Many Requests

这通常表示请求频率过高或额度不足。

解决方法：

• 降低请求频率；
• 增加重试机制；
• 使用指数退避；
• 检查账户额度；
• 联系平台提升限额。

Python 中可以简单实现重试：

import time

for i in range(3):
    response = requests.post(url, headers=headers, json=payload)
    if response.status_code != 429:
        break
    time.sleep(2 ** i)

4. 返回内容被截断

可能原因是 max_tokens 设置过小。解决方法是增大该值：

"max_tokens": 3000

同时也要注意，不同模型有不同的最大输出限制，应以官方文档为准。

十二、生产环境接入建议

如果只是本地测试，直接使用 curl 或 SDK 即可。但如果要在生产环境中调用 Claude API，建议注意以下几点。

1. 不要在前端暴露 API Key

错误示例：

const apiKey = "sk-ant-api03-xxxx";

这种写法非常危险。任何用户都可能通过浏览器开发者工具看到密钥。正确做法是：

• 前端请求你的后端；
• 后端保存 API Key；
• 后端调用 Claude API；
• 再把结果返回给前端。

2. 做好请求限流

为了避免用户恶意刷接口，建议在后端加入限流策略，例如：

• 按用户 ID 限流；
• 按 IP 限流；
• 按接口限流；
• 设置每日额度；
• 异常行为风控。

3. 记录调用日志

建议记录以下信息：

• 请求时间；
• 用户 ID；
• 模型名称；
• 输入 token；
• 输出 token；
• 请求耗时；
• 错误码；
• 业务场景。

但注意不要记录敏感隐私内容，尤其是用户密码、身份证号、银行卡号等。

4. 控制 token 成本

Claude API 通常按照 token 计费，因此要控制上下文长度和输出长度。优化方式包括：

• 精简 system prompt；
• 限制用户输入长度；
• 压缩历史对话；
• 对长文档先分块；
• 只传入与当前问题相关的内容；
• 根据场景选择合适模型。

5. 加入内容安全策略

如果你的产品面向公众用户，应加入内容审核、敏感词过滤、输出检查等机制。模型虽然能力强，但仍可能产生不准确、不合规或不适合直接发布的内容。对于医疗、法律、金融等高风险领域，更应设置人工审核或免责声明。

十三、完整可运行示例：Python 命令行聊天机器人

下面给出一个简化版的 Python 命令行聊天机器人示例，可以进行多轮对话。

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

messages = []

print("Claude 命令行聊天机器人已启动，输入 exit 退出。")

while True:
    user_input = input("\n你：")

    if user_input.lower() in ["exit", "quit"]:
        print("已退出。")
        break

    messages.append({
        "role": "user",
        "content": user_input
    })

    response = client.messages.create(
        model="claude-3-5-sonnet-latest",
        max_tokens=1000,
        system="你是一个友好、专业的中文AI助手。",
        messages=messages
    )

    assistant_text = response.content[0].text

    print("\nClaude：", assistant_text)

    messages.append({
        "role": "assistant",
        "content": assistant_text
    })

运行步骤：

pip install anthropic
export ANTHROPIC_API_KEY="你的_API_Key"
python chat.py

这个示例的核心逻辑是：每次用户输入后，把用户消息追加到 messages 数组中，再把完整上下文发送给 Claude。模型返回后，再把 Claude 的回复也加入历史消息中，从而实现多轮对话。

十四、总结

Claude API 的调用并不复杂，核心步骤可以概括为：

1. 获取 Anthropic API Key；
2. 设置请求 Header；
3. 调用 /v1/messages 接口；
4. 在请求体中指定 model、max_tokens 和 messages；
5. 解析返回结果中的 content[0].text；
6. 根据业务需要加入 system prompt、多轮上下文、流式输出和错误处理。

最基础的调用命令如下：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "请用中文介绍Claude API。"
      }
    ]
  }'

对于个人开发者，可以先从 curl 和 Python SDK 入手；对于企业或正式产品，则应重点关注 API Key 安全、请求限流、成本控制、日志监控和内容安全。只要合理设计架构，Claude API 可以较容易地接入网站、App、内部工具、知识库系统和自动化工作流，为业务带来强大的自然语言处理能力。