Developer Handbook

开发者层 完整手册

把 Claude 嵌进自有产品的全部细节——端点、参数、工具调用、流式、缓存、批处理、Claude Code 与 Managed Agents。概念讲清楚,代码可直接跑。

概览:这一层是什么

开发者层是蛋糕的第 4 层——面向开发者,按 token 计费、可程序化调用、成本可精确预算。是把 Claude 接入第三方产品的正路,也是 Agent 类应用的搭建基座。

与上层「终端应用层」(订阅制、人坐屏幕前用)最大的区别是:计费逻辑与可控性。订阅是固定月费 + 模糊的滚动额度;开发者层按 token 精确计费,每一次调用的成本都可预估、可优化。

1M 上下文 标准价不加价 缓存命中 降 90% 且不计入限流 Batch 降 50% 模型 ID 为 固定快照,可 pin 版本
本手册数据来源所有端点、参数、限流机制、SSE 事件类型均来自 platform.claude.com 官方文档(2026 年 6 月)。代码示例以 Opus 4.8 为例,可替换为任意模型 ID。

01端点总览

开发者层围绕 Messages 核心端点,外加批处理、模型查询、token 计数等配套端点。

POST/v1/messages核心对话 / 生成端点
POST/v1/messages/batches异步批量,成本立减 50%
POST/v1/messages/count_tokens发送前预估 token
GET/v1/models列出可用模型及规格

所有请求需带两个 header:x-api-keyanthropic-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);
SDK vs 直连官方强烈建议生产环境用 SDK(Python / TypeScript / PHP)——它们自动处理重试、流式累积、beta header 设置。直连 HTTP 仅在需要完全控制或非官方语言时使用。

03核心参数详解

Messages 端点的关键参数。注意 Opus 4.7+ 对采样参数有破坏性约束。

参数必填说明
model模型 ID,如 claude-opus-4-8
max_tokens最大输出 token;不计入 OTPM 限流,设高无副作用
messages对话数组,每条含 role(user/assistant)+ content
system系统提示,定义角色与约束;最适合做缓存前缀
tools工具定义数组,启用 function calling
streamtrue 时走 SSE 流式逐 token 返回
effort自适应思考强度;Opus 4.8 默认 high;Claude Code 可用 xhigh/max
stop_sequences遇到指定字符串即停止生成
metadata请求元数据(如 user_id),用于滥用监控
破坏性约束(Opus 4.7 起,4.8 沿用)非默认的 temperature / top_p / top_k 会返回 400 错误。自适应思考已替代旧的扩展思考开关。从 4.7→4.8 无新破坏性变更,分词器假定不变。

04工具调用 (Function Calling)

让模型按需调用你定义的函数——查数据库、调内部 API、触发动作。这是搭 Agent 的核心机制,也是 Claude 公认的强项。

完整调用流程(4 步)

STEP 1
定义工具
在请求里传 tools 数组,含 name / description / input_schema
STEP 2
模型请求调用
模型返回 stop_reason=tool_use 与一个 tool_use 块
STEP 3
你执行并回传
把结果以 tool_result 块附在新 user 消息里发回
STEP 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"
        }
    ]}
]
为什么 Claude 工具编排强在 MCP-Atlas 基准上 Opus 4.7 得 77.3%,领先 GPT-5.4 约 9.2 分。多工具、长链路、需要正确编排调用顺序的场景优势明显。TypeScript SDK 还提供 toolRunner() 自动跑工具循环。

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"}
生产环境 4 个坑① 工具参数在 input_json_delta,是需累积的字符串增量,不是完整 JSON;② SSE 不自动重连,需自己记录 last event id;③ 用户中途取消时,已生成 token 仍计费,别假设零成本;④ 流可能 200 开始后中途 error,别假设 200 就成功。

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" }
  }
]
最佳用途:系统提示 / 重复上下文 / 长文档 缓存命中按 10% 输入价计费 不计入限流 → 大幅提升有效吞吐
实战建议在 Console 的 Usage 页监控缓存命中率(cache_read_input_tokens)。对有长固定前缀、反复调用的负载(如 RAG、客服、文档问答),缓存往往是单笔最大的成本优化。

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)
全模型 降 50% 24h 内处理(异步) 可叠加提示缓存 支持 300k 输出 beta header

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可精确预算
90% 用户日活成本 < $30 限流按 5 小时滚动窗口 2026/05 起付费档限流 翻倍 effort 可用 xhigh / max
Agent Teams 成本Claude Code 可派生子代理,每个维护独立上下文、作为独立实例运行。3 代理团队约用 7× 单代理 token——并行加速的代价是成本成倍上升。本地 MCP server 需手动编辑配置文件,是已知上手门槛。

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 次,单独计费
Files / Batches / 代码执行 / 工具调用 全可用 支持 Webhooks(会话/凭证生命周期) 会话可按 status 过滤,事件可按 type 过滤

10错误码与限流

限流按模型独立计量,分三维度。缓存命中的 token 不计入限流——这是吞吐优化的关键。

限流三维度

维度全称说明
RPMRequests / Min每分钟请求数
ITPMInput Tokens / Min每分钟输入 token(多数模型仅计未缓存部分)
OTPMOutput Tokens / Min实时按实际生成计;max_tokens 不计入

错误码

含义处理
400请求无效(如非默认 temperature)检查/移除不支持的采样参数
413请求体过大直连无硬限;Vertex 30MB / Bedrock 20MB
429触发限流(含 retry-after 头)按 retry-after 退避;平滑放量
529服务过载(overloaded_error)指数退避重试
加速限制用量陡增也可能触发 429——即便没到层级上限。规避:逐步放量、保持稳定使用曲线,不要瞬间灌大流量。可在 Console 查看当前限流,或用 Rate Limits API 程序化读取。

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
优化顺序第一位永远是「选对模型族」——先把负载分类,再上缓存和批处理。顺序反了会先被总价吓退。用真实月 token 量代入测算,比看单价有意义得多。
数据时点 2026 年 6 月 · 旗舰 Claude Opus 4.8 · 端点/参数/限流/SSE 事件来自 platform.claude.com 官方文档,代码示例可直接运行(替换模型 ID 即可)。多项功能为 beta 且更新频繁,生产决策前请以官方文档为准。本手册为开发者层(蛋糕第 4 层)的深度展开。