Claude API 完整使用指南 2025：从入门到实战，含价格/模型/代码示例

📅 2025-04-29 ⏱ 阅读约 15 分钟 👁 14.6k 次阅读 🏷 API开发 · Anthropic · Python/JS

Claude API（Anthropic Messages API）是目前开发者在写作质量、长上下文处理和指令遵守方面评价最高的商业 LLM API 之一。截至2025年4月，最新主力模型是 claude-3-5-sonnet-20241022，HumanEval 92%，SWE-bench 49%。

本指南覆盖：模型选择与定价、Python/JavaScript 快速入门、提示缓存（节省最多60%费用）、流式输出、工具调用（Function Calling）、视觉API，以及速率限制和最佳实践。

📊 模型选择与价格（2025年4月）

模型	Input价格	Output价格	上下文	最适合场景
claude-3-5-sonnet-20241022	$3 /1M tokens	$15 /1M tokens	200K	主力推荐写作、代码、分析
claude-3-5-haiku-20241022	$0.80 /1M	$4 /1M	200K	高性价比高频调用、分类、摘要
claude-3-opus-20240229	$15 /1M	$75 /1M	200K	最复杂推理任务（Sonnet已覆盖大部分场景）
claude-3-haiku-20240307	$0.25 /1M	$1.25 /1M	200K	极低成本批量处理（旧版）

💡 模型选择建议

90% 的场景选 claude-3-5-sonnet：质量最好，价格合理（$3/$15 per 1M tokens）。
高频低复杂度任务选 claude-3-5-haiku：分类、意图识别、短文本摘要，成本是 Sonnet 的 26%，速度更快。
不需要选 Opus：3.5 Sonnet 在绝大多数基准上已超过 Claude 3 Opus，且价格只有 1/5。

🚀 快速入门（5分钟）

安装 SDK

    bash
# Python
pip install anthropic

# JavaScript/Node.js
npm install @anthropic-ai/sdk
  

Python 最简示例

    python
import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY"  # 或设置环境变量 ANTHROPIC_API_KEY
)

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用Python写一个二分查找函数，包含注释"}
    ]
)

print(message.content[0].text)
# 打印 token 使用量
print(f"Input tokens: {message.usage.input_tokens}")
print(f"Output tokens: {message.usage.output_tokens}")
  

JavaScript 示例

    javascript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const message = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello, Claude!' }]
});

console.log(message.content[0].text);
  

💾 提示缓存（最重要的省钱技巧）

提示缓存（Prompt Caching）是 Claude API 独有的功能，可以将固定的系统提示或文档缓存在服务端，之后相同前缀的请求 缓存命中时费用降低 90%，写入缓存费用为普通费率的 1.25×，但超过5分钟未使用缓存会失效。

典型节省场景

长系统提示：包含详细指令的system prompt（1000+ tokens），每次请求都重复发送
文档分析：上传同一份PDF多次提问，文档内容只需发送一次
代码库问答：将整个代码仓库内容缓存，多轮对话中反复引用
Few-shot示例：大量示例的prompt，缓存后多次使用

    python
# 提示缓存示例 — 缓存长系统提示
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是一个专业的代码审查员..." + long_guidelines,  # 数千字指南
            "cache_control": {"type": "ephemeral"}  # 标记此块为缓存目标
        }
    ],
    messages=[{"role": "user", "content": user_code}]
)

# 查看缓存使用情况
print(message.usage.cache_creation_input_tokens)  # 首次写入
print(message.usage.cache_read_input_tokens)     # 后续命中
  

💰 成本计算示例（系统提示 10,000 tokens，每天 1000 次请求）

无缓存：10K × $3/1M × 1000次$30/天

有缓存：首次写入 10K × $3.75/1M$0.038（一次性）

缓存命中：10K × $0.30/1M × 999次$3/天

节省90% ≈ $27/天 = $810/月

🌊 流式输出（Streaming）

对于需要实时显示响应的应用（聊天界面、代码生成），流式输出可以大幅提升用户体验，不需要等待完整响应。

    python
# 流式输出 — 实时打印每个 token
with client.messages.stream(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一篇关于机器学习的500字文章"}]
) as stream:
    for text in stream.text_stream():
        print(text, end="", flush=True)
  

🔧 工具调用（Tool Use / Function Calling）

工具调用让 Claude 可以调用你定义的函数，实现真正的 AI Agent 能力：查询数据库、调用外部API、执行代码等。

    python
# 定义工具
tools = [
    {
        "name": "get_weather",
        "description": "获取指定城市的当前天气",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市名称，如'北京'或'Singapore'"
                }
            },
            "required": ["city"]
        }
    }
]

# 发送请求，Claude 决定是否调用工具
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "新加坡今天天气怎么样？"}]
)

# 检查是否需要调用工具
if response.stop_reason == "tool_use":
    tool_use = response.content[-1]
    print(f"Claude 调用工具: {tool_use.name}")
    print(f"参数: {tool_use.input}")
    # → 此处执行实际的天气查询，将结果返回给 Claude
  

👁️ 视觉 API（图片分析）

    python
import base64

# 方式一：Base64 编码（本地图片）
with open("screenshot.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": image_data
                }
            },
            {"type": "text", "text": "请描述这张截图的内容，提取所有文字"}
        ]
    }]
)
print(message.content[0].text)

# 方式二：URL（直接传网络图片）
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=512,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "url", "url": "https://example.com/chart.png"}},
            {"type": "text", "text": "分析这个图表的趋势"}
        ]
    }]
)
  

⚡ 速率限制与最佳实践

速率限制（免费/Build/Scale层）

层级	RPM（请求/分钟）	TPM（tokens/分钟）	TPD（tokens/天）
Free（$0）	5	25,000	—
Build（充值$5+）	50	50,000	1,000,000
Scale（充值$500+）	1,000	80,000	不限
Enterprise	自定义	自定义	自定义

生产环境最佳实践

设置合理的 max_tokens：不要设置过高（如100000），实际需要多少设多少，节省成本
使用 system prompt：将固定指令放入 system 字段，比放在 user 消息中更清晰且可缓存
实现指数退避重试：遇到 429/529 错误时，用 2^n 秒等待后重试
启用提示缓存：凡是固定超过 1024 tokens 的内容都应标记 cache_control
批处理 API：非实时任务使用 Batch API，成本降低 50%，适合离线处理大量文档
监控 token 使用：在 usage 字段记录每次请求的 input/output tokens，及时发现异常

⚠️ 常见错误

401 Unauthorized：API Key 无效或未设置环境变量。
400 Bad Request：消息格式错误，检查 role 字段（必须是 "user" 或 "assistant" 交替）。
529 Overloaded：服务器过载，建议30秒后重试，生产环境实现自动重试逻辑。
context_length_exceeded：请求超过 200K token 限制，需要拆分输入。

💡 实战：完整的文档问答系统（30行代码）

    python
import anthropic

client = anthropic.Anthropic()

def document_qa(document: str, question: str) -> str:
    """基于文档内容回答问题，使用提示缓存降低成本"""
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=512,
        system="你是文档问答助手。只基于提供的文档内容回答，如果文档中没有相关信息，请明确说明。",
        messages=[
            {
                "role": "user",
                "content": [
                    # 文档内容 — 标记为缓存（多次提问时只发送一次）
                    {
                        "type": "text",
                        "text": f"<document>\n{document}\n</document>",
                        "cache_control": {"type": "ephemeral"}
                    },
                    # 具体问题 — 每次不同，不缓存
                    {"type": "text", "text": question}
                ]
            }
        ]
    )
    return response.content[0].text

# 使用示例
doc = open("report.txt").read()
print(document_qa(doc, "这份报告的核心结论是什么？"))
print(document_qa(doc, "文中提到了哪些具体数字？"))  # 第2次问题命中缓存，节省90%成本
  