Claude API接口调用教程｜附配置文件

随着大模型应用的快速发展，越来越多的开发者开始将 Claude 接入到自己的产品、工作流或自动化系统中。Claude 是 Anthropic 推出的高性能大语言模型系列，适合用于智能问答、内容生成、代码辅助、数据分析、知识库问答、客服机器人、Agent 应用等场景。

本文将系统介绍 Claude API 的调用方式，包括接口基本概念、账号与 Key 准备、请求参数说明、curl 调用示例、Python 调用示例、Node.js 调用示例、常见配置文件写法、错误排查以及实际开发中的最佳实践。文章面向初学者和有一定开发经验的工程师，阅读后你可以较为完整地掌握 Claude API 的接入流程。

一、Claude API 简介

Claude API 是 Anthropic 提供的模型调用接口，开发者可以通过 HTTP 请求的方式，将用户输入发送给 Claude 模型，并接收模型生成的回复。

与在网页端直接使用 Claude 不同，API 调用更适合程序化场景。例如：

• 在网站中接入 AI 聊天助手；
• 为企业内部系统增加文档问答能力；
• 自动生成营销文案、邮件、摘要；
• 构建代码审查、代码解释、代码生成工具；
• 将 Claude 集成到工作流自动化平台中；
• 搭建基于 RAG 的知识库系统；
• 开发多轮对话机器人或智能 Agent。

Claude API 的核心调用方式通常是向指定接口发送一个 JSON 请求体，请求体中包含模型名称、消息内容、最大输出长度、温度参数等信息。

二、调用 Claude API 前的准备工作

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

1. 注册 Anthropic 账号

首先需要访问 Anthropic 官方平台并注册账号。注册完成后，进入控制台获取 API Key。

通常流程如下：

1. 打开 Anthropic Console；
2. 登录或注册账号；
3. 找到 API Keys 管理页面；
4. 创建一个新的 API Key；
5. 将 API Key 保存到安全位置。

需要注意的是，API Key 只会完整显示一次。生成后应立即复制并妥善保存，不建议直接写入业务代码中。

2. 准备开发环境

根据你的技术栈，可以选择不同语言调用 Claude API。常见方式包括：

• 使用 curl 直接请求；
• 使用 Python 的 requests 或官方 SDK；
• 使用 Node.js 的 fetch、axios 或官方 SDK；
• 在后端服务中封装统一的 Claude 调用模块。

如果你只是测试接口，推荐先使用 curl。如果你要在项目中长期使用，建议通过环境变量和配置文件统一管理参数。

3. 理解 API Key 的安全性

API Key 相当于你的接口访问凭证，一旦泄露，别人可能使用你的额度产生费用。因此在开发过程中需要遵循以下原则：

• 不要将 API Key 写死在前端代码中；
• 不要将 API Key 上传到 GitHub 等公开仓库；
• 不要在日志中打印完整 API Key；
• 推荐使用 .env 文件或服务器环境变量保存；
• 定期轮换 API Key；
• 如果发现泄露，应立即删除旧 Key 并重新生成。

三、Claude API 基础请求结构

Claude 的接口调用通常需要设置请求地址、请求头和请求体。

一个典型的请求包括以下部分：

1. 请求地址

Claude Messages API 的常见请求地址如下：

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

2. 请求头

请求头中一般需要包含：

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

说明如下：

其中 anthropic-version 是 Anthropic API 版本声明。不同版本可能在字段规范上略有差异，实际项目中建议固定版本，避免后续接口升级导致兼容性问题。

3. 请求体

一个基础请求体示例如下：

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

字段说明：

四、使用 curl 调用 Claude API

如果你想快速验证 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-20241022",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "请写一段关于人工智能未来发展的中文短文。"
      }
    ]
  }'

如果配置正确，你将收到类似下面的响应：

{
  "id": "msg_xxxxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-3-5-sonnet-20241022",
  "content": [
    {
      "type": "text",
      "text": "人工智能正在深刻改变人类社会..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 120
  }
}

其中，模型回复内容通常位于：

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-20241022",
    "max_tokens": 1500,
    "system": "你是一名资深后端工程师，擅长用清晰、严谨的方式解释 API 接口调用流程。",
    "messages": [
      {
        "role": "user",
        "content": "请解释 REST API 和大模型 API 调用之间的相同点与不同点。"
      }
    ]
  }'

system 提示词非常重要，它会影响模型回答的风格、角色、边界和格式。在实际项目中，可以将 system prompt 写入配置文件，方便维护和迭代。

五、Python 调用 Claude API

Python 是调用大模型 API 最常用的语言之一，适合做脚本、后端服务、数据处理和 AI 应用原型。

下面以 requests 为例进行说明。

1. 安装依赖

pip install requests python-dotenv

requests 用于发送 HTTP 请求，python-dotenv 用于读取 .env 配置文件。

2. 创建 .env 配置文件

在项目根目录创建 .env 文件：

ANTHROPIC_API_KEY=你的Claude_API_Key
ANTHROPIC_API_URL=https://api.anthropic.com/v1/messages
ANTHROPIC_API_VERSION=2023-06-01
CLAUDE_MODEL=claude-3-5-sonnet-20241022

注意：.env 文件不要提交到 Git 仓库。可以在 .gitignore 中添加：

.env

3. Python 示例代码

创建 claude_demo.py：

import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("ANTHROPIC_API_KEY")
API_URL = os.getenv("ANTHROPIC_API_URL", "https://api.anthropic.com/v1/messages")
API_VERSION = os.getenv("ANTHROPIC_API_VERSION", "2023-06-01")
MODEL = os.getenv("CLAUDE_MODEL", "claude-3-5-sonnet-20241022")

def call_claude(prompt: str):
    headers = {
        "x-api-key": API_KEY,
        "anthropic-version": API_VERSION,
        "content-type": "application/json"
    }

    payload = {
        "model": MODEL,
        "max_tokens": 1024,
        "system": "你是一名专业中文技术助手，回答要清晰、准确、有条理。",
        "messages": [
            {
                "role": "user",
                "content": prompt
            }
        ]
    }

    response = requests.post(API_URL, headers=headers, json=payload, timeout=60)

    if response.status_code != 200:
        print("请求失败：", response.status_code)
        print(response.text)
        return None

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

if __name__ == "__main__":
    result = call_claude("请用中文解释什么是 API 鉴权。")
    print(result)

运行：

python claude_demo.py

4. 封装为可复用模块

在实际项目中，不建议每个业务函数都直接写请求代码。可以封装一个统一的 Claude 客户端。

例如创建 claude_client.py：

import os
import requests
from dotenv import load_dotenv

load_dotenv()

class ClaudeClient:
    def __init__(self):
        self.api_key = os.getenv("ANTHROPIC_API_KEY")
        self.api_url = os.getenv("ANTHROPIC_API_URL", "https://api.anthropic.com/v1/messages")
        self.api_version = os.getenv("ANTHROPIC_API_VERSION", "2023-06-01")
        self.model = os.getenv("CLAUDE_MODEL", "claude-3-5-sonnet-20241022")

        if not self.api_key:
            raise ValueError("缺少 ANTHROPIC_API_KEY，请检查环境变量或 .env 文件。")

    def chat(self, user_message, system_prompt=None, max_tokens=1024, temperature=0.7):
        headers = {
            "x-api-key": self.api_key,
            "anthropic-version": self.api_version,
            "content-type": "application/json"
        }

        payload = {
            "model": self.model,
            "max_tokens": max_tokens,
            "temperature": temperature,
            "messages": [
                {
                    "role": "user",
                    "content": user_message
                }
            ]
        }

        if system_prompt:
            payload["system"] = system_prompt

        response = requests.post(
            self.api_url,
            headers=headers,
            json=payload,
            timeout=60
        )

        response.raise_for_status()
        data = response.json()

        return data["content"][0]["text"]

然后在业务代码中调用：

from claude_client import ClaudeClient

client = ClaudeClient()

answer = client.chat(
    user_message="请总结一下微服务架构的优缺点。",
    system_prompt="你是一名资深架构师，请用条理化方式回答。",
    max_tokens=1200,
    temperature=0.5
)

print(answer)

这种方式更利于维护，也更适合在 Web 服务、定时任务、Agent 系统中复用。

六、Node.js 调用 Claude API

如果你的项目使用 Node.js，例如 Express、Next.js、NestJS 或其他 JavaScript/TypeScript 框架，也可以很方便地调用 Claude API。

1. 初始化项目

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

安装依赖：

npm install dotenv

如果你的 Node.js 版本低于 18，可能还需要安装 node-fetch。Node.js 18 及以上版本已内置 fetch。

2. 创建 .env 文件

ANTHROPIC_API_KEY=你的Claude_API_Key
ANTHROPIC_API_URL=https://api.anthropic.com/v1/messages
ANTHROPIC_API_VERSION=2023-06-01
CLAUDE_MODEL=claude-3-5-sonnet-20241022

3. Node.js 示例代码

创建 index.js：

require("dotenv").config();

const API_KEY = process.env.ANTHROPIC_API_KEY;
const API_URL = process.env.ANTHROPIC_API_URL || "https://api.anthropic.com/v1/messages";
const API_VERSION = process.env.ANTHROPIC_API_VERSION || "2023-06-01";
const MODEL = process.env.CLAUDE_MODEL || "claude-3-5-sonnet-20241022";

async function callClaude(prompt) {
  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "anthropic-version": API_VERSION,
      "content-type": "application/json"
    },
    body: JSON.stringify({
      model: MODEL,
      max_tokens: 1024,
      system: "你是一名专业中文技术助手，回答要准确、简洁、有结构。",
      messages: [
        {
          role: "user",
          content: prompt
        }
      ]
    })
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Claude API 请求失败：${response.status} ${errorText}`);
  }

  const data = await response.json();
  return data.content[0].text;
}

(async () => {
  try {
    const result = await callClaude("请用中文解释什么是 Token，以及它在大模型 API 中的作用。");
    console.log(result);
  } catch (error) {
    console.error(error);
  }
})();

运行：

node index.js

七、配置文件示例

在企业项目中，推荐将 Claude API 的配置拆分出来，方便不同环境使用不同模型和参数。例如开发环境、测试环境、生产环境可以使用不同的模型、超时时间和最大输出长度。

下面给出几种常见配置方式。

1. .env 配置文件

适用于简单项目或本地开发：

# Claude API Key
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

# API 地址
ANTHROPIC_API_URL=https://api.anthropic.com/v1/messages

# API 版本
ANTHROPIC_API_VERSION=2023-06-01

# 默认模型
CLAUDE_MODEL=claude-3-5-sonnet-20241022

# 默认生成参数
CLAUDE_MAX_TOKENS=1024
CLAUDE_TEMPERATURE=0.7

# 请求超时时间，单位秒
CLAUDE_TIMEOUT=60

优点：

• 简单易用；
• 适合本地开发；
• 多数语言和框架都支持读取环境变量。

缺点：

• 不适合保存复杂结构；
• 多环境管理时需要额外工具；
• 需要注意安全，避免提交到代码仓库。

2. YAML 配置文件

适合较复杂项目，例如需要多个模型配置、多套提示词模板或不同业务场景参数。

创建 config.yaml：

claude:
  api_url: "https://api.anthropic.com/v1/messages"
  api_version: "2023-06-01"
  model: "claude-3-5-sonnet-20241022"
  max_tokens: 1024
  temperature: 0.7
  timeout: 60

prompts:
  default_system: "你是一名专业中文技术助手，回答要清晰、准确、有条理。"
  code_reviewer: "你是一名资深代码审查专家，请从安全性、可读性、性能和可维护性角度进行分析。"
  copywriter: "你是一名经验丰富的中文文案专家，擅长写简洁、有吸引力的商业文案。"

features:
  enable_stream: false
  enable_retry: true
  max_retry_times: 3

如果使用 Python 读取 YAML，可以安装：

pip install pyyaml

示例代码：

import yaml

with open("config.yaml", "r", encoding="utf-8") as f:
    config = yaml.safe_load(f)

print(config["claude"]["model"])
print(config["prompts"]["default_system"])

需要注意的是，YAML 文件中不建议直接写入 API Key。API Key 仍然推荐通过环境变量注入。

3. JSON 配置文件

如果你的项目更偏前后端工程化，也可以使用 JSON 配置：

{
  "claude": {
    "api_url": "https://api.anthropic.com/v1/messages",
    "api_version": "2023-06-01",
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "temperature": 0.7,
    "timeout": 60
  },
  "prompts": {
    "default_system": "你是一名专业中文技术助手，回答要清晰、准确、有条理。",
    "technical_writer": "你是一名技术文档专家，请用 Markdown 格式输出内容。",
    "data_analyst": "你是一名数据分析专家，请用严谨的逻辑分析问题。"
  }
}

JSON 的优点是格式清晰、跨语言兼容性强，缺点是不支持注释，维护较复杂配置时可读性不如 YAML。

八、多轮对话调用方式

Claude API 的 messages 字段支持传入多轮对话上下文。多轮对话的关键是将历史消息按顺序传入模型。

示例：

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "什么是微服务？"
    },
    {
      "role": "assistant",
      "content": "微服务是一种软件架构风格，它将一个大型应用拆分为多个小型、独立的服务..."
    },
    {
      "role": "user",
      "content": "那它和单体架构相比有什么优势？"
    }
  ]
}

模型会根据前面的上下文继续回答最后一个问题。

不过，多轮对话并不是把所有历史消息无限制地塞进去。因为上下文会消耗 Token，也会增加费用和延迟。实际项目中可以采用以下策略：

• 只保留最近 N 轮对话；
• 对较早历史进行摘要；
• 将关键信息写入长期记忆；
• 对无关内容进行裁剪；
• 对用户会话做 Token 预算控制。

九、流式输出简介

在聊天类产品中，如果等待模型完整生成后再返回，用户可能会感觉响应较慢。因此很多场景会使用流式输出。

流式输出的效果类似网页聊天机器人逐字显示回答。它的优点是：

• 首字响应更快；
• 用户体验更好；
• 适合长文本生成；
• 便于前端实时渲染。

调用流式输出时，通常需要在请求体中加入：

"stream": true

示例结构：

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "请写一篇关于低代码平台发展的文章。"
    }
  ]
}

流式响应一般以 Server-Sent Events，也就是 SSE 的形式返回。后端需要逐段读取响应数据，并转发给前端。对于普通脚本调用，非流式更容易处理；对于聊天应用，流式输出通常是更好的选择。

十、常见参数说明

1. model

指定要调用的 Claude 模型。不同模型在能力、速度、价格和上下文长度上可能不同。选择模型时可以根据任务复杂度判断：

• 简单问答：可选择更轻量、更便宜的模型；
• 复杂推理：选择能力更强的模型；
• 长文档分析：选择上下文更长的模型；
• 代码生成：选择在代码能力上表现较好的模型。

2. max_tokens

控制模型最大输出长度。它不是输入长度，而是输出上限。

如果设置过小，模型可能回答不完整；如果设置过大，可能增加费用和等待时间。建议根据业务场景设置合理值：

3. temperature

控制模型输出的随机性。值越低，回答越稳定；值越高，回答越发散。

常见设置：

如果你希望结果更可控，建议降低 temperature。如果你希望生成内容更有创意，可以适当提高。

十一、错误排查

调用 Claude API 时，可能会遇到各种错误。下面列出一些常见问题。

1. 401 Unauthorized

可能原因：

• API Key 未设置；
• API Key 写错；
• API Key 已失效；
• 请求头字段名不正确。

解决方法：

• 检查环境变量是否加载成功；
• 确认请求头中使用的是 x-api-key；
• 重新生成 API Key；
• 避免 Key 前后包含空格或换行。

2. 400 Bad Request

可能原因：

• JSON 格式错误；
• 缺少必填字段；
• model 名称错误；
• messages 格式不符合要求；
• max_tokens 设置异常。

解决方法：

• 使用 JSON 校验工具检查请求体；
• 对照官方文档确认字段；
• 确认 messages 是数组；
• 确认每条消息包含 role 和 content。

3. 429 Rate Limit

表示请求频率超过限制，或额度不足。解决方法：

• 降低请求并发；
• 增加重试与退避机制；
• 检查账户额度；
• 根据业务优先级做请求排队。

重试时不要简单地立即重复请求，建议使用指数退避策略，例如等待 1 秒、2 秒、4 秒、8 秒逐步增加。

4. 500 或 529 服务异常

这类错误通常与服务端临时状态有关。解决方式：

• 稍后重试；
• 增加超时控制；
• 对重要请求做重试机制；
• 在业务侧增加降级方案。

十二、生产环境最佳实践

如果你计划在生产环境中长期使用 Claude API，建议重点关注以下方面。

1. 统一封装调用层

不要在多个业务模块中直接调用 Claude API。推荐封装统一的客户端，例如：

• ClaudeClient
• LLMService
• AIModelGateway

这样可以统一处理鉴权、日志、异常、重试、超时、模型切换和监控。

2. 做好日志记录

建议记录以下信息：

• 请求时间；
• 用户 ID 或业务 ID；
• 模型名称；
• 输入 Token 数；
• 输出 Token 数；
• 响应耗时；
• 错误码；
• 请求状态。

但不要记录敏感信息，例如完整 API Key、用户隐私数据、机密文档内容等。

3. 控制成本

大模型 API 通常按 Token 计费，因此成本控制非常重要。

常见方法包括：

• 限制单次输入长度；
• 限制最大输出 Token；
• 对长文档先分块再摘要；
• 对重复问题使用缓存；
• 针对不同任务选择不同模型；
• 对低价值请求设置更低的输出上限；
• 对用户调用频次做限制。

4. 提示词版本管理

提示词本质上是 AI 应用的重要业务逻辑。建议像管理代码一样管理提示词：

• 将提示词写入配置文件；
• 为不同场景设置不同 prompt；
• 记录 prompt 版本；
• 对 prompt 进行 A/B 测试；
• 定期评估输出质量；
• 避免频繁无记录地修改线上 prompt。

5. 增加内容安全策略

在面向用户的产品中，建议增加内容安全处理：

• 对用户输入做基础过滤；
• 对模型输出做敏感信息检测；
• 对高风险问题设置拒答策略；
• 避免模型泄露系统提示词；
• 对企业知识库内容做权限控制。

十三、一个完整的项目目录示例

下面给出一个 Python 项目的参考结构：

claude-api-demo/
├── .env
├── .gitignore
├── config.yaml
├── requirements.txt
├── main.py
├── claude_client.py
└── README.md

requirements.txt：

requests
python-dotenv
pyyaml

.gitignore：

.env
__pycache__/
*.pyc

main.py：

from claude_client import ClaudeClient

def main():
    client = ClaudeClient()

    result = client.chat(
        user_message="请用 Markdown 格式写一份 Claude API 调用流程清单。",
        system_prompt="你是一名技术文档专家，输出要结构清晰。",
        max_tokens=1500,
        temperature=0.4
    )

    print(result)

if __name__ == "__main__":
    main()

这样一个简单项目就可以完成 Claude API 的基础调用，并具备一定的扩展性。

十四、总结

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

1. 注册 Anthropic 账号并获取 API Key；
2. 在环境变量或配置文件中保存 Key；
3. 准备请求地址、请求头和请求体；
4. 通过 curl、Python 或 Node.js 发起请求；
5. 从响应中的 content 字段读取模型回复；
6. 在生产环境中加入异常处理、重试、日志、成本控制和安全策略。

对于个人开发者来说，建议先用 curl 跑通基础调用，再使用 Python 或 Node.js 封装成函数。对于企业项目来说，建议将 Claude API 调用封装为统一服务，并使用配置文件管理模型、参数和提示词。

只要掌握好接口结构、参数设置和配置管理，你就可以把 Claude 方便地接入到聊天机器人、知识库问答、内容生成、代码助手和自动化工作流等各种应用中。