Claude API 基础入门使用教程

编辑部发布 2026-06-25 更新 2026-06-27 10 分钟阅读 1,889 字

Claude API 允许您通过编程方式调用 Anthropic 的大语言模型，将 Claude 的对话、文本生成、代码编写等能力无缝集成到您的应用、脚本或工作流中。核心流程可概括为：获取 API Key → 构建请求（消息格式）→ 调用 API → 处理响应。本文将循序渐进地带您走通这一流程，并揭示新手最容易遇到的陷阱与规避策略。

前置条件

在开始之前，请确认满足以下三个前提条件。任何一步的缺失都可能导致后续步骤失败，这也是入门最常见的阻塞点。

Anthropic 控制台账号：访问 console.anthropic.ai 注册。注意，部分地区的手机号可能无法接收验证短信，建议优先使用 Gmail 或 Outlook 邮箱注册。
API Key：登录后，在控制台左侧导航进入 API Keys 页面，点击 Create Key 生成密钥。复制后妥善保存（关闭页面后将无法再次查看完整 Key）。
开发环境：至少需要一个能发送 HTTPS 请求的环境。Python 3.7+ 是最常见的搭配，Node.js 18+ 也可行。本文示例基于 Python 环境。

版本说明：Anthropic 的 API 文档和 SDK 版本更新较为频繁。本文基于 anthropic Python SDK 0.25.x 版本编写（2025 年早期版本）。若您阅读时 SDK 已发布大版本更新，请以官方文档为准。官方 SDK 的 GitHub 仓库和 PyPI 页面是最准确的参考来源。

操作步骤

以下五个步骤将引导您完成首次成功的 API 调用。建议严格按顺序操作，避免跳跃到中间步骤。

1. 安装 SDK

pip install anthropic

确认安装成功：

pip show anthropic
# 输出应包含 Version: 0.25.x

常见陷阱：在虚拟环境外安装，导致后续脚本找不到包。建议先在项目目录下创建并激活虚拟环境（如 python -m venv venv）。

2. 设置 API Key

提供两种设置方式：

环境变量（推荐）：
```
export ANTHROPIC_API_KEY="sk-ant-你的key"
```
在 Python 脚本中无需显式传入 Key，SDK 会自动读取。
代码中直接传入（仅限快速测试）：
```
client = anthropic.Anthropic(api_key="sk-ant-你的key")
```
警告：切勿将 API Key 硬编码后提交到公开仓库。已有大量案例因 Key 泄露导致账户被盗用，产生高额费用。

3. 编写第一个调用脚本

创建文件 claude_hello.py：

import anthropic

client = anthropic.Anthropic()

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

print(message.content[0].text)

4. 运行脚本

python claude_hello.py

正常输出类似：

API 是应用程序之间相互通信的一组规则和协议，让不同软件能够交换数据和功能。

5. 理解响应结构

返回的 message 对象包含多个关键字段。初学者最容易只关注 content，而忽略其他重要信息：

字段	类型	说明	常用场景
`content`	list	模型回复内容列表，通常第一个元素是文本	提取回复文本
`model`	str	实际使用的模型名称	日志记录、成本核算
`usage.input_tokens`	int	输入消耗的 token 数	计费统计
`usage.output_tokens`	int	输出消耗的 token 数	计费统计
`stop_reason`	str	停止原因（`end_turn`、`max_tokens` 等）	判断输出是否被截断

关键检查点：确认 stop_reason 是否为 "end_turn"。如果是 "max_tokens"，说明输出被截断，需增大 max_tokens。

验证检查

完成上述步骤后，使用以下检查确认设置正确。若任何一项不通过，请不要急于继续下一步。

环境变量加载检查：在 Python 中运行 import os; print(os.getenv("ANTHROPIC_API_KEY"))。如果输出 None，说明环境变量未设置或未在当前 shell 中生效。
网络连通性检查：运行 curl -I https://api.anthropic.com。如能返回 HTTP 状态头，网络正常。如果超时，可能需要配置代理或检查防火墙。
SDK 版本检查：运行 python -c "import anthropic; print(anthropic.__version__)"，确保版本在 0.25.x 范围内。
模型名称有效性检查：在 Anthropic 控制台的 Models 页面或官方文档中，确认使用的模型名称（如 claude-3-5-sonnet-20241022）仍在服务列表内。废弃的模型会导致 404 或 400 错误。

常见问题排查

以下三个问题是新手最常遇到的，对照检查可快速定位问题。

401 Authentication Error

Error code: 401 - {"error": {"type": "authentication_error", "message": "invalid x-api-key"}}

可能原因：API Key 无效或已过期。
检查方法：确认 Key 以 sk-ant- 开头，长度为 108 个字符左右。前往控制台 API Keys 页面查看该 Key 是否仍处于 Active 状态。
最佳做法：如果 Key 泄露或怀疑泄露，立即在控制台删除并重新生成。

400 Invalid Request (model name error)

Error code: 400 - {"error": {"type": "invalid_request_error", "message": "model: [...]"}}

可能原因：模型名称拼写错误，或试图调用对您不可用的模型。
检查方法：逐字符对比模型名称与官方文档，注意 - 和 . 的位置。
回退方案：将模型切换为 claude-3-haiku-20240307，这是最稳定的入门模型，对初学者限制更少。

529 Overloaded Error

Error code: 529 - {"error": {"type": "overloaded_error", "message": "Overloaded"}}

可能原因：API 服务器暂时过载，通常与配额无关。
处理方法：等待几秒后重试。如果应用对延迟敏感，可实现指数退避重试逻辑。
停止操作时机：连续重试超过 5 次仍返回 529，建议停止操作并检查 Anthropic Status Page 确认是否存在大规模故障。

常见问题解答（FAQ）

Claude API 基础入门使用指南是什么？

这是一套指导开发者从零开始使用 Anthropic Claude API 的实操指南，涵盖账号准备、SDK 安装、首次 API 调用、参数配置以及常见错误排查。与单独阅读官方文档相比，本指南更强调实操步骤和避坑建议。

如何操作 Claude API 基础入门？

核心操作流程为：注册账号 → 获取 API Key → 安装 SDK → 编写调用代码 → 解析返回结果。具体步骤见本文操作步骤部分。一个完整的参考示例是：使用 claude-3-haiku 模型制作一个简单的翻译工具，输入英文句子，返回中文翻译。

Claude API 入门常见错误有哪些？

最常见的有三个：API Key 未正确设置导致 401 错误、模型名称写错导致 400 错误、以及未检查 stop_reason 导致误以为输出完整但实际被截断。详见常见问题排查部分。

实践建议

建议从 claude-3-haiku 模型开始。它的 token 成本最低（约为 Sonnet 的五分之一），响应速度快，容错空间大。先用 Haiku 跑通流程、验证提示词逻辑，再迁移到更强大的 Sonnet 或 Opus 模型处理复杂任务。

成本控制提醒：在 Anthropic 控制台的 Usage & Cost 页面设置预算警报。API 调用按使用量计费，一个无限循环的 bug 可能在几分钟内消耗数百美元。建议使用测试专用账号进行开发和调试，这比直接操作主力账号更安全。