开发者层 完整手册
把 Claude 嵌进自有产品的全部细节——端点、参数、工具调用、流式、缓存、批处理、Claude Code 与 Managed Agents。概念讲清楚,代码可直接跑。
概览:这一层是什么
开发者层是蛋糕的第 4 层——面向开发者,按 token 计费、可程序化调用、成本可精确预算。是把 Claude 接入第三方产品的正路,也是 Agent 类应用的搭建基座。
与上层「终端应用层」(订阅制、人坐屏幕前用)最大的区别是:计费逻辑与可控性。订阅是固定月费 + 模糊的滚动额度;开发者层按 token 精确计费,每一次调用的成本都可预估、可优化。
01端点总览
开发者层围绕 Messages 核心端点,外加批处理、模型查询、token 计数等配套端点。
所有请求需带两个 header:x-api-key 与 anthropic-version: 2023-06-01。每个响应都返回 request-id(全局唯一)和 anthropic-organization-id。
02快速开始
最小可运行调用。三种方式:cURL(理解原始结构)、Python SDK、TypeScript SDK。
# 安装:无需,直接 HTTP 调用 curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "你是一个资深解决方案工程师。", "messages": [ {"role": "user", "content": "用一句话解释提示缓存。"} ] }'
# 安装:pip install anthropic import anthropic client = anthropic.Anthropic() # 自动读取 ANTHROPIC_API_KEY message = client.messages.create( model="claude-opus-4-8", max_tokens=1024, system="你是一个资深解决方案工程师。", messages=[ {"role": "user", "content": "用一句话解释提示缓存。"} ], ) print(message.content[0].text)
// 安装:npm install @anthropic-ai/sdk import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // 读取 ANTHROPIC_API_KEY const message = await client.messages.create({ model: "claude-opus-4-8", max_tokens: 1024, system: "你是一个资深解决方案工程师。", messages: [ { role: "user", content: "用一句话解释提示缓存。" } ], }); console.log(message.content[0].text);
03核心参数详解
Messages 端点的关键参数。注意 Opus 4.7+ 对采样参数有破坏性约束。
| 参数 | 必填 | 说明 |
|---|---|---|
| model | 是 | 模型 ID,如 claude-opus-4-8 |
| max_tokens | 是 | 最大输出 token;不计入 OTPM 限流,设高无副作用 |
| messages | 是 | 对话数组,每条含 role(user/assistant)+ content |
| system | 否 | 系统提示,定义角色与约束;最适合做缓存前缀 |
| tools | 否 | 工具定义数组,启用 function calling |
| stream | 否 | true 时走 SSE 流式逐 token 返回 |
| effort | 否 | 自适应思考强度;Opus 4.8 默认 high;Claude Code 可用 xhigh/max |
| stop_sequences | 否 | 遇到指定字符串即停止生成 |
| metadata | 否 | 请求元数据(如 user_id),用于滥用监控 |
04工具调用 (Function Calling)
让模型按需调用你定义的函数——查数据库、调内部 API、触发动作。这是搭 Agent 的核心机制,也是 Claude 公认的强项。
完整调用流程(4 步)
"tools": [{ "name": "get_weather", "description": "查询指定城市的当前天气,返回温度与天气状况", "input_schema": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名,如 北京" } }, "required": ["city"] } }]
// 模型的响应(stop_reason 变为 "tool_use") { "stop_reason": "tool_use", "content": [ { "type": "tool_use", "id": "toolu_01A09q90...", "name": "get_weather", "input": { "city": "北京" } } ] }
# 执行函数后,把结果作为新一轮 user 消息回传 messages=[ {"role": "user", "content": "北京天气怎么样?"}, {"role": "assistant", "content": previous_content}, # 含 tool_use {"role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90...", "content": "晴,22°C" } ]} ]
05流式输出 SSE
设 stream:true 用 Server-Sent Events 逐 token 返回。聊天界面、长文生成、Agent 工具调用必备——否则用户盯着空屏,长输出还可能超时。
9 种事件类型与流程
| 事件 | 含义 |
|---|---|
| message_start | 含空 content 的 Message 对象,流开始 |
| content_block_start | 一个内容块开始(按 index 区分) |
| content_block_delta | 增量:text_delta(文本)/ input_json_delta(工具参数)/ thinking_delta(思考) |
| content_block_stop | 该内容块结束 |
| message_delta | 顶层变化;累计 token 用量在此 |
| message_stop | 流结束 |
| ping / error | 心跳 / 流中错误(如 overloaded_error → 529) |
with client.messages.stream( model="claude-opus-4-8", max_tokens=1024, messages=[{"role": "user", "content": "写一首关于海的短诗"}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True)
const stream = await client.messages.create({ model: "claude-opus-4-8", max_tokens: 1024, messages: [{ role: "user", content: "写一首关于海的短诗" }], stream: true, }); for await (const event of stream) { if (event.type === "content_block_delta") process.stdout.write(event.delta.text ?? ""); }
event: message_start
data: {"type":"message_start","message":{...}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,
"delta":{"type":"text_delta","text":"海"}}
event: message_stop
data: {"type":"message_stop"}06提示缓存 (Prompt Caching)
把固定的长前缀(系统提示、知识库、文档)缓存起来,命中部分按基础输入价 10% 计费——降 90%,且不计入限流。
在要缓存的 system 或 content 块上加 cache_control 标记即可。Opus 4.8 把可缓存最小 token 从 4,096 降到 1,024,短系统提示也能用上。
"system": [ { "type": "text", "text": "<大段固定知识库 / 长文档 / 系统指令...>", "cache_control": { "type": "ephemeral" } } ]
07批处理 API (Message Batches)
异步批量处理,成本立减 50%,24 小时内完成。适合离线打标、大规模内容生成等不要求实时的任务。
batch = client.messages.batches.create( requests=[ { "custom_id": "req-1", "params": { "model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role":"user","content":"翻译这段..."}] } }, # ... 可批量成千上万条 ] ) print(batch.id)
# 轮询批次状态,完成后取结果 result = client.messages.batches.retrieve(batch.id) if result.processing_status == "ended": for entry in client.messages.batches.results(batch.id): print(entry.custom_id, entry.result)
08Claude Code
Agent 式编码工具,从 CLI / 桌面 / 移动端委派编码任务,能读写代码库、跑命令、迭代调试、集成 MCP。
# 安装(需 Node.js) npm install -g @anthropic-ai/claude-code # 在项目目录启动 cd your-project claude # 鉴权:可用 Pro/Max 订阅额度,或 API key 按 token 计费
计费方式
| 方式 | 计费 | 说明 |
|---|---|---|
| Pro ($20/月) | 标准滚动额度 | 含全部模型 + Claude Code |
| Max 5×/20× ($100/$200) | 5×/20× 额度 + 优先 | 全天高强度开发不撞限 |
| API(按 token) | Sonnet $3/$15、Opus $5/$25 | 可精确预算 |
09Managed Agents(托管 Agent)
Anthropic 托管的 Agent 基础设施,免自建检索/执行/编排。需 beta header,多代理会话与 Outcomes 已进入公开 beta。
所有 Managed Agents 请求需带 managed-agents-2026-04-01 beta header(SDK 自动设置)。事件双向流动:你发 user events 启动并引导会话;系统回 session / span / agent events 供观测。事件命名遵循 {domain}.{action} 约定。
计费两个维度
| 维度 | 说明 |
|---|---|
| Token | 会话内所有 token 按 Model Pricing 计,缓存乘数同样适用 |
| 会话运行时 | 按 session runtime 另计 |
| 会话内网页搜索 | $10 / 1,000 次,单独计费 |
10错误码与限流
限流按模型独立计量,分三维度。缓存命中的 token 不计入限流——这是吞吐优化的关键。
限流三维度
| 维度 | 全称 | 说明 |
|---|---|---|
| RPM | Requests / Min | 每分钟请求数 |
| ITPM | Input Tokens / Min | 每分钟输入 token(多数模型仅计未缓存部分) |
| OTPM | Output Tokens / Min | 实时按实际生成计;max_tokens 不计入 |
错误码
| 码 | 含义 | 处理 |
|---|---|---|
| 400 | 请求无效(如非默认 temperature) | 检查/移除不支持的采样参数 |
| 413 | 请求体过大 | 直连无硬限;Vertex 30MB / Bedrock 20MB |
| 429 | 触发限流(含 retry-after 头) | 按 retry-after 退避;平滑放量 |
| 529 | 服务过载(overloaded_error) | 指数退避重试 |
11成本优化总表
实际账单不取决于头部单价,而取决于这几个杠杆叠加。
| 杠杆 | 效果 | 适用条件 |
|---|---|---|
| 模型分层路由 | 视负载 | 简单→Haiku,多数→Sonnet,最难→Opus |
| 提示缓存 | 命中输入 降 90% | 有固定长前缀反复使用 |
| 批处理 Batch | 全模型 降 50% | 可异步、不要求实时 |
| 缓存 + 批处理叠加 | 最多 降 95% | 两者条件同时满足 |
成本测算(1000万输入 + 200万输出)
| 模型 | 标准成本 | 叠加优化后 |
|---|---|---|
| Haiku 4.5 | 约 $20 | 约 $1–4 |
| Sonnet 4.6 | 约 $60 | 约 $3–12 |
| Opus 4.8 | 约 $100 | 约 $5–20 |