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

随着大语言模型在内容生成、代码辅助、智能客服、数据分析、知识库问答等场景中的广泛应用，越来越多的开发者开始将 AI 能力集成到自己的业务系统中。Claude 是 Anthropic 推出的系列大语言模型，具备较强的文本理解、推理、总结、代码生成和长上下文处理能力。对于开发者来说，通过 Claude API 可以非常方便地把 Claude 模型接入到网站、后台服务、自动化工具或企业内部系统中。

本文将围绕 Claude API 接口调用 展开，详细介绍接口准备、环境配置、请求参数、调用示例、配置文件管理、错误处理以及实际项目中的封装建议。文章末尾会附上常用配置文件示例，方便你直接参考使用。

一、Claude API是什么？

Claude API 是 Anthropic 提供给开发者的模型调用接口。开发者可以通过 HTTP 请求向 Claude 模型发送消息，并获取模型返回的结果。

简单来说，你可以把 Claude API 理解为一个远程 AI 服务：

• 你向接口发送用户问题、上下文、系统提示词等内容；
• Claude 模型根据你的输入进行理解和生成；
• 接口返回模型生成的文本内容；
• 你的应用程序再把结果展示给用户或用于后续业务处理。

Claude API 常用于以下场景：

1. 智能对话机器人
2. 文章写作与润色
3. 代码生成与代码审查
4. 客服问答系统
5. 知识库问答
6. 合同、文档、报告摘要
7. 数据分析解释
8. 自动化办公助手

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

在正式调用 Claude API 之前，需要完成几个基础准备步骤。

1. 注册 Anthropic 账号

首先需要访问 Anthropic 官方平台，注册并登录账号。登录后通常可以进入控制台，创建 API Key。

API Key 是调用 Claude API 的身份凭证，类似于访问密码。服务端在请求 Claude API 时，需要在请求头中携带该 Key。

注意：API Key 非常敏感，不要直接写在前端代码中，也不要提交到 GitHub 等公开代码仓库。

2. 获取 API Key

在控制台中创建 API Key 后，你会得到一个类似下面格式的字符串：

sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

这个 Key 只会展示一次或有限次数，建议你立即复制并保存到安全的位置。

推荐保存方式：

• 使用环境变量；
• 使用服务器密钥管理工具；
• 使用 .env 文件并加入 .gitignore；
• 使用云平台 Secret Manager；
• 不要硬编码在业务代码中。

3. 确认API接口地址

Claude API 的常见接口地址为：

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

该接口通常用于消息式对话调用。开发者向该接口发送模型名称、消息内容、最大输出 token 数等参数，即可获得 Claude 的回复。

三、Claude API核心请求参数说明

调用 Claude API 时，常见请求参数主要包括以下几个。

1. model

model 用于指定要调用的 Claude 模型。例如：

"model": "claude-3-5-sonnet-20241022"

不同模型在速度、能力、价格、上下文长度等方面可能有所不同。实际使用时可以根据业务场景选择：

• 对质量要求高：选择能力更强的模型；
• 对响应速度要求高：选择轻量模型；
• 对成本敏感：选择价格更低的模型；
• 对长文档处理有要求：选择支持长上下文的模型。

2. max_tokens

max_tokens 用于控制模型最大输出长度。例如：

"max_tokens": 1024

该值越大，模型最多可输出的内容越长，但也可能带来更高成本和更长响应时间。

如果是短问答，可以设置为 512 或 1024；如果是文章生成、报告总结，可以设置为 2000、4000 或更高。

3. temperature

temperature 用于控制输出内容的随机性。

"temperature": 0.7

一般来说：

如果你希望模型每次回答尽可能一致，可以设置较低温度；如果你希望内容更丰富、更有变化，可以适当提高。

4. system

system 用于设置系统提示词，也就是给模型设定角色、规则和输出风格。

例如：

"system": "你是一名专业的中文技术文档作者，回答要清晰、准确，并使用Markdown格式。"

系统提示词在实际应用中非常重要。它决定了模型回答的方向、语气、边界和格式。

常见用途包括：

• 指定模型角色；
• 限制回答范围；
• 要求输出 JSON；
• 要求使用中文；
• 要求避免编造；
• 要求以某种风格生成内容。

5. messages

messages 是对话消息数组，用于传递用户输入和上下文。

基本格式如下：

"messages": [
  {
    "role": "user",
    "content": "请介绍一下Claude API的使用方法"
  }
]

在多轮对话中，可以追加历史消息：

"messages": [
  {
    "role": "user",
    "content": "什么是Claude API？"
  },
  {
    "role": "assistant",
    "content": "Claude API是Anthropic提供的大语言模型接口。"
  },
  {
    "role": "user",
    "content": "它适合哪些应用场景？"
  }
]

需要注意的是，多轮对话并不是 API 自动记忆，而是你需要在每次请求中携带必要的历史上下文。

四、使用curl调用Claude API

最简单的调用方式是使用 curl 命令。

1. 基础请求示例

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "temperature": 0.7,
    "system": "你是一名专业的中文技术助手，回答要简洁清晰。",
    "messages": [
      {
        "role": "user",
        "content": "请用中文介绍Claude API的基本调用流程。"
      }
    ]
  }'

其中：

• x-api-key：你的 API Key；
• anthropic-version：API 版本；
• Content-Type：请求体格式；
• model：调用的模型；
• messages：用户输入内容。

2. 返回结果示例

接口返回结果通常类似：

{
  "id": "msg_xxxxxxxxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-3-5-sonnet-20241022",
  "content": [
    {
      "type": "text",
      "text": "Claude API的基本调用流程包括：获取API Key、配置请求头、构造请求参数、发送HTTP请求并解析返回结果。"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

实际项目中，你通常需要读取：

content[0].text

来获取 Claude 的文本回复。

五、使用Python调用Claude API

Python 是调用 AI 接口最常见的语言之一，适合后端服务、脚本工具和自动化任务。

下面以 requests 库为例演示。

1. 安装依赖

pip install requests python-dotenv

2. 创建.env文件

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

ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_URL=https://api.anthropic.com/v1/messages
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
ANTHROPIC_VERSION=2023-06-01

同时建议在 .gitignore 中加入：

.env

避免密钥泄露。

3. Python调用示例

创建 main.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")
MODEL = os.getenv("ANTHROPIC_MODEL", "claude-3-5-sonnet-20241022")
VERSION = os.getenv("ANTHROPIC_VERSION", "2023-06-01")


def call_claude(prompt: str) -> str:
    headers = {
        "x-api-key": API_KEY,
        "anthropic-version": VERSION,
        "Content-Type": "application/json"
    }

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

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

    if response.status_code != 200:
        raise Exception(f"Claude API调用失败：{response.status_code}, {response.text}")

    data = response.json()

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


if __name__ == "__main__":
    result = call_claude("请用三点说明Claude API适合哪些开发场景。")
    print(result)

运行：

python main.py

如果配置正确，你将看到 Claude 返回的中文内容。

六、使用Node.js调用Claude API

如果你的项目是前端工程、Node.js 后端或 Next.js 服务，也可以使用 JavaScript 调用 Claude API。

强烈建议在服务端调用 Claude API，不要在浏览器前端直接暴露 API Key。

1. 初始化项目

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

Node.js 18 及以上版本已经内置 fetch，无需额外安装请求库。

2. 创建.env文件

ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_URL=https://api.anthropic.com/v1/messages
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
ANTHROPIC_VERSION=2023-06-01

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 MODEL = process.env.ANTHROPIC_MODEL || "claude-3-5-sonnet-20241022";
const VERSION = process.env.ANTHROPIC_VERSION || "2023-06-01";

async function callClaude(prompt) {
  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "anthropic-version": VERSION,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: MODEL,
      max_tokens: 1024,
      temperature: 0.7,
      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 () => {
  const result = await callClaude("请介绍Claude API在企业知识库问答中的应用。");
  console.log(result);
})();

运行：

node index.js

七、附：Claude API配置文件示例

在真实项目中，不建议把模型名称、温度、最大 token、系统提示词等参数全部写死在代码里。更好的方式是使用配置文件统一管理。

下面提供几种常见配置文件示例。

1. .env配置文件

.env 适合保存环境变量，尤其适合保存 API Key。

# Claude API密钥
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

# API版本
ANTHROPIC_VERSION=2023-06-01

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

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

建议 .gitignore 中加入：

.env
.env.local
.env.production

2. config.json配置文件

config.json 适合保存业务配置，例如模型参数、提示词模板等。

{
  "claude": {
    "apiUrl": "https://api.anthropic.com/v1/messages",
    "version": "2023-06-01",
    "model": "claude-3-5-sonnet-20241022",
    "maxTokens": 1024,
    "temperature": 0.7,
    "systemPrompt": "你是一名专业的中文AI助手，回答要准确、清晰、有条理。"
  }
}

Python 读取示例：

import json

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

claude_config = config["claude"]

print(claude_config["model"])

Node.js 读取示例：

const config = require("./config.json");

console.log(config.claude.model);

3. config.yaml配置文件

YAML 文件可读性更强，适合配置较复杂的项目。

claude:
  api_url: "https://api.anthropic.com/v1/messages"
  version: "2023-06-01"
  model: "claude-3-5-sonnet-20241022"
  max_tokens: 1024
  temperature: 0.7
  system_prompt: |
    你是一名专业的中文AI助手。
    回答问题时请遵循以下规则：
    1. 使用中文回答；
    2. 结构清晰，优先使用Markdown；
    3. 不确定的信息请明确说明；
    4. 不要编造不存在的事实。

Python 读取 YAML 需要安装依赖：

pip install pyyaml

读取示例：

import yaml

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

claude_config = config["claude"]

print(claude_config["system_prompt"])

八、封装一个可复用的Claude客户端

在实际项目中，如果每次调用都手写请求代码，维护成本会比较高。建议封装一个 Claude Client。

下面是一个 Python 版示例。

import os
import requests
from typing import List, Dict, Optional


class ClaudeClient:
    def __init__(
        self,
        api_key: str,
        api_url: str = "https://api.anthropic.com/v1/messages",
        version: str = "2023-06-01",
        model: str = "claude-3-5-sonnet-20241022",
        timeout: int = 60
    ):
        self.api_key = api_key
        self.api_url = api_url
        self.version = version
        self.model = model
        self.timeout = timeout

    def chat(
        self,
        messages: List[Dict[str, str]],
        system: Optional[str] = None,
        max_tokens: int = 1024,
        temperature: float = 0.7
    ) -> str:
        headers = {
            "x-api-key": self.api_key,
            "anthropic-version": self.version,
            "Content-Type": "application/json"
        }

        payload = {
            "model": self.model,
            "max_tokens": max_tokens,
            "temperature": temperature,
            "messages": messages
        }

        if system:
            payload["system"] = system

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

        if response.status_code != 200:
            raise RuntimeError(
                f"Claude API请求失败，状态码：{response.status_code}，响应：{response.text}"
            )

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

使用方式：

from dotenv import load_dotenv
import os

load_dotenv()

client = ClaudeClient(
    api_key=os.getenv("ANTHROPIC_API_KEY"),
    model=os.getenv("ANTHROPIC_MODEL", "claude-3-5-sonnet-20241022")
)

answer = client.chat(
    system="你是一名专业的中文技术顾问。",
    messages=[
        {
            "role": "user",
            "content": "请解释什么是大语言模型API。"
        }
    ],
    max_tokens=1000,
    temperature=0.5
)

print(answer)

这样做的好处是：

• 统一管理请求逻辑；
• 方便增加错误处理；
• 方便支持多模型切换；
• 方便记录日志；
• 方便后续扩展流式输出、重试机制等功能。

九、常见错误与解决方法

调用 Claude API 时，可能会遇到一些常见错误。

1. 401 Unauthorized

通常表示 API Key 错误或没有携带 API Key。

检查项：

x-api-key 是否正确
API Key 是否过期
环境变量是否成功读取
请求头名称是否写错

2. 400 Bad Request

通常表示请求参数有问题。

可能原因包括：

• model 名称错误；
• messages 格式不正确；
• max_tokens 类型错误；
• 请求体不是合法 JSON；
• 缺少必要字段。

建议打印请求参数，并对照官方文档检查。

3. 429 Too Many Requests

表示请求过于频繁，触发限流。

解决方法：

• 降低请求频率；
• 增加重试机制；
• 使用指数退避；
• 检查是否存在并发过高；
• 根据业务情况申请更高额度。

4. 500 或 529 服务异常

这类错误通常是服务端临时问题或高负载导致。

建议：

• 增加自动重试；
• 设置合理超时时间；
• 对用户展示友好提示；
• 记录错误日志；
• 不要无限重试。

十、接口调用的最佳实践

为了让 Claude API 在生产环境中稳定运行，建议遵循以下实践。

1. 不要在前端暴露API Key

API Key 一旦暴露，可能被他人恶意调用，造成费用损失。正确做法是：

前端页面 -> 你的后端服务 -> Claude API

由后端统一管理密钥和调用权限。

2. 设置合理的max_tokens

max_tokens 不宜盲目设置过大。过大的输出长度会增加响应时间和费用。

建议根据不同业务设置不同参数：

3. 使用清晰的系统提示词

好的系统提示词可以显著提高输出质量。

示例：

你是一名专业的企业知识库问答助手。
请只根据提供的资料回答问题。
如果资料中没有相关信息，请回答“根据当前资料无法确定”。
不要编造事实。
回答请使用简体中文。

这类提示词适合 RAG 知识库问答场景，可以有效减少模型幻觉。

4. 增加日志与监控

生产系统中建议记录：

• 请求时间；
• 使用模型；
• 输入 token；
• 输出 token；
• 响应耗时；
• 错误状态码；
• 用户 ID 或业务标识。

但要注意，不要在日志中记录敏感信息，例如 API Key、用户隐私、密码、身份证号等。

5. 增加重试机制

对于网络波动、临时限流、服务端异常，可以增加重试机制。

示例策略：

第一次失败：等待1秒
第二次失败：等待2秒
第三次失败：等待4秒
超过次数后返回错误

这就是常见的指数退避策略。

十一、流式输出简介

如果你希望实现类似 ChatGPT 或 Claude 网页版那样的“逐字输出”效果，可以使用流式响应。

流式输出的优点：

• 用户感知速度更快；
• 长文本生成体验更好；
• 适合聊天机器人；
• 可以边生成边展示。

不过流式接口的处理方式比普通接口稍复杂，需要服务端持续读取事件流，并将内容转发给前端。对于初学者，建议先掌握普通接口调用，再进一步学习流式输出。

十二、一个完整项目结构建议

如果你准备在项目中正式接入 Claude API，可以参考下面的目录结构：

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

其中：

• .env：保存 API Key 和环境变量；
• .gitignore：忽略敏感文件；
• config.json：保存模型和业务参数；
• requirements.txt：保存 Python 依赖；
• claude_client.py：封装 Claude API 调用；
• main.py：业务入口；
• README.md：项目说明文档。

requirements.txt 示例：

requests==2.32.3
python-dotenv==1.0.1
PyYAML==6.0.2

十三、总结

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

1. 注册 Anthropic 账号并获取 API Key；
2. 配置环境变量或配置文件；
3. 构造请求头和请求体；
4. 通过 HTTP POST 请求调用接口；
5. 解析返回结果；
6. 在项目中封装客户端并增加错误处理。

对于个人开发者，可以先使用 curl、Python 或 Node.js 快速测试；对于企业项目，则建议使用配置文件管理参数，并通过后端服务统一调用 Claude API，避免密钥泄露。

本文提供了 .env、config.json、config.yaml 等配置文件示例，也给出了 Python 和 Node.js 的基础调用代码。你可以根据自己的项目语言和业务需求进行调整。

如果你是第一次接入 Claude API，建议从最简单的 curl 示例开始，确认 API Key 和模型参数可用后，再逐步封装到正式项目中。这样可以减少排查成本，也更容易定位问题。