Python中Claude API入门指南

本文是一份面向Python开发者的Claude API实用指南。你将学习如何从零开始设置环境、发送第一个请求，并掌握响应处理、系统提示和流式传输等关键概念，为构建生产级应用打下基础。

环境准备与安装

首先，你需要Python 3.9或更高版本，以及一个免费的Claude Console账户。在Console的Settings > API Keys页面生成API密钥，并建议添加至少5美元的信用额度。安装官方SDK只需一行命令：pip install anthropic。

务必通过环境变量管理API密钥，而非硬编码在代码中。在终端执行export ANTHROPIC_API_KEY="YOUR-API-KEY-HERE"，或者使用python-dotenv将其写入.env文件。SDK会自动从环境变量中读取密钥。

首次API调用

所有交互的入口是client.messages.create()方法。你需要提供三个参数：模型ID、max_tokens限制和消息列表。消息列表由字典组成，每个字典包含"role"和"content"键。

以下代码让Claude用一句话解释“上下文窗口”：

import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-sonnet-5", max_tokens=256, messages=[ {"role": "user", "content": "用一句话解释什么是上下文窗口？"} ] ) print(response.content[0].text)

max_tokens是输出令牌数的硬上限，建议根据任务需求设置足够大。消息列表必须以"user"角色开头。

理解响应对象

messages.create()返回一个Message对象，包含多个重要字段：

• id: 消息唯一标识
• type: 固定为'message'
• role: 固定为'assistant'
• content: 文本块列表（通常只有一个TextBlock）
• model: 使用的模型
• stop_reason: 停止原因，'end_turn'表示正常结束，'max_tokens'表示被限制截断
• stop_sequence: 停止序列（通常为None）
• usage: 包含input_tokens和output_tokens，用于计费监控

通过response.content[0].text即可提取生成的文本。

使用系统提示

系统提示允许你为Claude设置持久角色、约束或上下文。通过最顶层的system参数传入，而非放在消息列表中。例如：

response = client.messages.create( model="claude-sonnet-5", max_tokens=512, system="你是一名Python代码审查员。仅回复改进后的Python代码，除非用户明确要求，否则不要解释改动。", messages=[ {"role": "user", "content": "def get_user(id):\n db = connect()\n return db.query('SELECT * FROM users WHERE id=' + id)"} ] ) print(response.content[0].text)

系统提示在整个对话中保持权威性，因此角色指令、格式规则等只需设定一次。

流式响应

对于耗时较长的请求，流式传输可让用户实时看到输出。SDK通过client.messages.stream()实现，作为上下文管理器使用：

with client.messages.stream( model="claude-sonnet-5", max_tokens=512, messages=[ {"role": "user", "content": "请逐步说明Python列表容量不足时发生了什么？"} ] ) as stream: for chunk in stream.text_stream: print(chunk, end="", flush=True)

上下文管理器确保连接正确关闭。如需获取完整的Message对象（包含令牌计数），可在块结束前调用stream.get_final_message()。

下一步

现在你已经掌握了核心概念：请求、结构化响应、系统提示和流式传输。接下来可以学习错误处理、令牌使用优化和多轮对话。由于API是无状态的，每次请求都需要发送完整对话历史。官方文档提供了推荐做法。

API参考中还包含结构化输出和工具使用等功能。祝探索愉快！