Claude API：自己写程序调 Claude

不通过 Claude Code，自己写几行代码直接调模型，要哪些东西、请求和响应长什么样、多轮对话和流式怎么做。本文按官方的入门文档整理，每一步都通过中转站跑过。要改的只有接口地址和 key 两处。另外测到一个新手很容易踩的坑：max_tokens 给 100，回答是空的。

官方给 Claude 的接口配了七种语言的 SDK、一个命令行和两个兼容层。本文整理各自怎么装、适合谁，并做了实测：对着假服务器看 Python SDK 的重试和超时（碰到带 retry-after 60 的 503，它等了两分钟才报错）；用 OpenAI 的 SDK 调 Claude；通过中转站用官方命令行 ant。

Fable 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.5 各管什么、官方价是多少、模型 ID 为什么不带日期、哪些老模型快下线了。本文按官方文档整理，并通过中转站实测了几件事：同一个任务在三个模型上差四倍多的钱；同一段中文在新旧模型上 token 数几乎一样，英文却多出近四成。

调 Claude 的接口时，请求没成功是一回事，成功了但回答停得不对是另一回事。本文整理官方的十一个报错状态码、两种限额、七个停止原因和拒答的处理办法，并通过中转站用 Python SDK 把能触发的都触发了一遍：报错的类型名、限流的响应头、停止序列等好几处和官方文档不一样。

effort 控制 Claude 在一个回答上下多大功夫，思考只是其中一部分。本文整理五档的含义、各模型的默认值、思考怎么计费、怎么让它多想或少想，以及任务预算和快速模式。实测一道排期题：Sonnet 5.5 在 low 和 medium 上十次全错，调到 high 五次全对；再调到 max 要花三倍多的钱，答案一样。

提示缓存让重复发送的那段开头按十分之一甚至更低的价格计费。本文整理两种开法、响应里三个数字怎么读、哪些改动会让缓存失效、缓存诊断、数 token 和上下文窗口。通过中转站实测：不做处理时十次里只命中一次；请求里带上固定的 metadata.user_id 之后，七次里命中六到七次。

长对话和跑很久的智能体迟早要处理上下文：要么让服务端把旧的轮次写成摘要（压缩），要么按规则清掉旧的工具结果和思考（上下文编辑）。本文整理两类办法的用法、限制和对缓存的影响。通过中转站实测：上下文编辑能用；两种压缩都用不了，其中一种是参数被悄悄忽略。

老提示词在 Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1 上基本能直接用，但每个模型有几处行为变了。本文把官方四份指南整理成一张“看到什么现象，改什么”的表，列出该删掉的老写法。实测一道要 JSON 答案的推理题：不思考时模型把推理写进回答里，答案是对的，但整段不再是合法的 JSON。

用 Claude 做的应用上线之前，怎么知道它够不够好，怎么防它乱说、被带偏、把系统提示说出去、回得太慢。本文整理官方的六页指南，并通过中转站做了五个小实验：十二条的分类评测、文档里没有的问题、邮件里夹带的指令、套系统提示、流式的首字时间。

把模型名换成 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.1，有几处老写法会直接报 400：强制调用工具、关掉思考、预填回答。还有几处不报错但结果变了：回答的第一块可能是空的 thinking，max_tokens 可能被思考用光。本文按官方迁移指南整理，能试的都通过中转站实测过。

让 Claude 调你自己的函数：怎么定义工具、怎么把结果送回去、一次调多个工具怎么处理、出错怎么告诉它，以及 strict、Tool Runner 和流式参数。例子都在服务器上通过中转站跑过，并列出和官方文档不一样的地方。

跑命令、改文件、跨对话记东西、操作桌面和浏览器，这几类工具 Anthropic 已经定义好，你只负责执行。本文在服务器上用 bash 加文本编辑器搭了一个最小的改代码智能体，并实测记忆工具；电脑和浏览器操作按文档整理。

这几个工具由 Anthropic 的服务器执行，你只管在请求里打开。本文整理各自的用法、计费和限制，以及工具太多时怎么省上下文。通过中转站实测：联网搜索、工具搜索、顾问能用；抓取网页、MCP 连接器被拒，代码执行被悄悄忽略。

程序要解析 Claude 的回答，就用结构化输出；要让用户核对回答的依据，就用引用。本文通过中转站实测两者的用法，并记下两个坑：可选字段写在必填字段前面会被漏掉，中文的纯文本文档不会被自动分句。

图片和 PDF 怎么发、各占多少 token、让它返回的坐标怎么对回原图，本文通过中转站逐项实测。Files API、批量处理和向量这三样这家中转站没有开，按官方文档整理用法、限制和价格。

长对话中途改顶层的 system 或 tools，前面的缓存全部作废。Claude 5.5 这一代可以在消息列表里追加一条 system 消息来加指令、增减工具。通过中转站实测：加指令能用、缓存保住了；按名字增减工具报 400。

直接调接口也能用 skill，但它跑在 Anthropic 的代码执行容器里，和 Claude Code 里的不是一套。本文按官方文档整理用法、限制和写法；这家中转站用不了这组接口。另在服务器上实测了 Claude Code 自带的 claude-api skill。

一个人一把 key 没什么可管的；团队用、上生产，就要分清 key 的类型，用工作区隔开环境和项目，会查用量和花费，知道数据留多久。本文按官方文档整理。这些是官方控制台的功能，通过中转站用不到。

Claude Managed Agents 把智能体的循环、工具执行和会话状态放到 Anthropic 那边运行。本文按官方文档整理它的四个概念、最小流程、工具和权限策略、事件怎么收发，以及从自己写的循环迁过来要改什么。中转站没有这组接口，全文未实测。

托管智能体跑起来以后要解决的事：沙箱能访问哪些网站、文件和代码怎么放进去、第三方服务的密钥怎么不让它看到、怎么跨会话记东西、怎么定义做完的标准、怎么给花费封顶、怎么定时跑。按官方文档整理，全文未实测。

一个智能体忙不过来时，可以让它把活派给子智能体，或者自己写一段工作流让几百个智能体在后台跑；数据不能出内网时，可以把工具的执行搬到自己的机器上。本文按官方文档整理这两部分的用法、上限和安全分工，全文未实测。