【weelinking系列Claude教程】 02 - Claude API 开发实战

02 – Claude API 开发实战

从零开始调用 Claude API，包含完整可运行的代码示例。 weelinking企业级API中转站

1. 环境准备

1.1 获取 API Key

weelinking解决方案（国内直连）

Anthropic官方办法（需要极高的网络环境=纯净美国IP）

1.2 安装 SDK

# Python SDK
pip install anthropic

# JavaScript/TypeScript SDK
npm install @anthropic-ai/sdk

1.3 配置 API Key

# 方式一：环境变量（推荐）

# Windows PowerShell 临时生效
$env:ANTHROPIC_BASE_URL = "https://api.weelinking.com"
#复制你刚刚创建的密钥替换
$env:ANTHROPIC_API_KEY = "sk你刚刚创建的密钥复制替换这个字符串"

# Windows PowerShell 永久生效 #每个命令要执行5秒钟，不是卡了
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.weelinking.com", [System.EnvironmentVariableTarget]::User)
#复制你刚刚创建的密钥替换
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk替换成你创建的密钥", [System.EnvironmentVariableTarget]::User)

# Windows CMD
set ANTHROPIC_BASE_URL = "https://api.weelinking.com"
set ANTHROPIC_API_KEY=sk替换成你创建的密钥

# Linux / macOS
export ANTHROPIC_BASE_URL = "https://api.weelinking.com"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 方式二：在代码中直接传入（不推荐用于生产环境）
# client = Anthropic(api_key="sk-ant-xxxxx", base_url="https://api.weelinking.com")

2. 第一个 API 调用

完整代码见 examples/api_hello.py

2.1 最简单的调用

from anthropic import Anthropic

client = Anthropic()

message = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=1024,
messages=[
{"role": "user", "content": "用一句话介绍你自己。"}
]
)

print(message.content[0].text)
# 输出示例：我是 Claude，由 Anthropic 开发的 AI 助手，擅长分析、写作和编程。

2.2 Messages API 核心参数

2.3 响应结构

# message 对象的关键属性
message.id # 消息 ID
message.content # 内容块列表（TextBlock, ToolUseBlock 等）
message.model # 使用的模型
message.role # "assistant"
message.stop_reason # "end_turn" | "max_tokens" | "tool_use"
message.usage # token 使用统计
.input_tokens # 输入 token 数
.output_tokens # 输出 token 数

3. System Prompt — 控制 Claude 的行为

System Prompt 是你给 Claude 的"角色说明书"，放在 system 参数中：

message = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=1024,
system="你是一位资深 Python 开发者，回答简洁专业，必要时给出代码示例。",
messages=[
{"role": "user", "content": "Python 中 list 和 tuple 的核心区别？"}
]
)

System Prompt 最佳实践：

• 明确角色和专业领域
• 指定输出格式和风格
• 设定约束条件（如字数限制、语言）
• 提供背景信息

4. 多轮对话

Claude 通过 messages 数组中交替的 user 和 assistant 消息来维护对话历史：

conversation = [
{"role": "user", "content": "什么是递归？"},
{"role": "assistant", "content": "递归是函数调用自身的编程技术…"},
{"role": "user", "content": "给我一个 Python 例子。"}
]

message = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=1024,
messages=conversation
)

注意事项：

• 消息必须以 user 开头
• user 和 assistant 必须交替出现
• 每轮对话都会消耗输入 token（包括历史消息）
• 长对话注意 token 用量控制

💡 国内访问 Claude和Codex： weelinking – 直连、稳定、不折腾

5. Streaming（流式输出）

完整代码见 examples/api_streaming.py

流式输出让 Claude 逐 token 返回结果，适合聊天界面等需要实时显示的场景：

with client.messages.stream(
model="claude-sonnet-4-5-20250514",
max_tokens=512,
messages=[{"role": "user", "content": "写一首关于编程的小诗"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)

流式 vs 非流式：

6. Tool Use（工具调用）

完整代码见 examples/api_tool_use.py

Tool Use 让 Claude 调用你定义的函数，与外部世界交互。

6.1 工作流程

用户请求 → Claude 判断需要工具 → 返回 tool_use
→ 你的代码执行工具 → 结果发回 Claude → Claude 生成最终回答

6.2 定义工具

tools = [
{
"name": "get_weather",
"description": "获取指定城市的当前天气信息",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称，如：北京"
}
},
"required": ["city"]
}
}
]

6.3 处理工具调用

response = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=1024,
tools=tools,
messages=messages,
)

if response.stop_reason == "tool_use":
for block in response.content:
if block.type == "tool_use":
# block.name = "get_weather"
# block.input = {"city": "北京"}
# block.id = "toolu_xxx"
result = your_function(**block.input)
# 将结果发回 Claude…

6.4 实战：天气查询 + 数学计算

运行 examples/api_tool_use.py 可以看到 Claude 如何：

• 识别用户意图并选择合适的工具
• 一次调用多个工具
• 组合工具结果生成最终回答

7. Extended Thinking（扩展思维）

完整代码见 examples/api_extended_thinking.py

让 Claude 在回复前进行深度思考，显著提升复杂推理的准确度：

response = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 8000 # 思考预算
},
messages=[{"role": "user", "content": "你的复杂问题…"}]
)

# 响应包含 thinking 块和 text 块
for block in response.content:
if block.type == "thinking":
print("思考过程:", block.thinking)
elif block.type == "text":
print("最终回答:", block.text)

思考预算建议：

8. 多模态（Vision & PDF）

完整代码见 examples/api_multimodal.py

8.1 图片分析

import base64

# 读取图片并转为 base64
with open("image.png", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=1024,
messages=[{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
{"type": "text", "text": "描述这张图片。"}
],
}],
)

8.2 PDF 分析

with open("document.pdf", "rb") as f:
pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=4096,
messages=[{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": pdf_data,
},
},
{"type": "text", "text": "总结这份文档的要点。"}
],
}],
)

9. Prompt Caching（提示缓存）

对于重复使用相同 System Prompt 的场景，缓存可大幅降低成本：

response = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=1024,
system=[
{
"type": "text",
"text": "你是一个专业的法律顾问…" * 100, # 长 System Prompt
"cache_control": {"type": "ephemeral"} # 启用缓存
}
],
messages=[{"role": "user", "content": "问题…"}]
)

# 查看缓存效果
print(f"缓存读取 tokens: {response.usage.cache_read_input_tokens}")
print(f"缓存创建 tokens: {response.usage.cache_creation_input_tokens}")

缓存有效期： 5 分钟（短期），可配置为 1 小时（长期）

10. 错误处理

from anthropic import (
Anthropic,
APIError,
AuthenticationError,
RateLimitError,
)

client = Anthropic()

try:
message = client.messages.create(
model="claude-sonnet-4-5-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}]
)
except AuthenticationError:
print("API Key 无效，请检查 ANTHROPIC_API_KEY")
except RateLimitError:
print("请求过于频繁，请稍后重试")
except APIError as e:
print(f"API 错误: {e.status_code} – {e.message}")

11. 实战代码文件清单

💡 国内访问 Claude和Codex： weelinking – 直连、稳定、不折腾

上一篇： 01-Claude 模型全解析 下一篇： 03-Prompt Engineering 实战指南