示例面向 Anthropic 原生 Claude API，其他云平台需要使用各自的认证和模型标识。

第一次调用 Opus 5.5，先只做一件事：发送一个短问题，正确读取文字结果和结束原因。确认链路正常后，再加缓存、工具、文件和流式输出，避免一开始同时排查太多配置。

一、先准备环境，不要把密钥写进代码

需要一个可用的 Claude Console 组织、相应模型权限和可用额度。创建密钥后，在自己的环境里配置 ANTHROPIC_API_KEY。

密钥应放在环境变量或服务端的安全配置里，不放到浏览器前端，也不要复制到日志截图和公开仓库。下面代码只读取环境变量，不包含真实密钥。

安装 SDK：

python3 -m pip install -U anthropic

在实际项目中，建议使用独立虚拟环境，并记录验证过的 SDK 版本。遇到“参数不认识”，先检查运行的 Python 和安装包是不是同一个环境。

图：最小调用先跑通文字请求，再分别处理正文、结束原因和用量。

二、最小 Python 示例

把下面内容保存为 demo.py，在设置好密钥的环境中运行 python3 demo.py：

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "用三点说明长上下文是什么。"}
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print("stop_reason:", response.stop_reason)
print("usage:", response.usage.model_dump_json())

运行示例前，先核实自己的模型权限和可用额度；发送真实请求可能产生费用。返回文字并不表示任务永远完整，还要看结束原因。

三、为什么不能直接读取 content[0].text？

Opus 5.5 使用始终开启的自适应思考，返回内容可能先出现思考块，随后才是正文。第一块内容不一定有你想读取的 text。

所以，示例根据 block.type 读取文字。如果以后加入工具，也要分别处理工具调用和工具结果，不能把所有内容拼成普通字符串就当作完整会话。

工具循环中，需要按接口要求完整保留相关助手内容，包括思考块。随意删除、改写或重排，可能影响后续请求。

四、这几个参数最常用

max_tokens=4096 是演示用上限，不是所有任务的最佳设置。复杂工作可能需要更大预算；不需要长回答时，也应明确规定输出内容。

五、这些旧写法不要照搬

5.5 不支持关闭思考，也不支持旧式手动思考预算。不要从旧版本示例中复制 thinking.type="disabled"，然后只修改模型名称。

此外，强制工具调用的 tool_choice 类型 any 和指定 tool 不适用于这个版本。只做普通文字对话时，不需要设置这一项。

采样参数和预填助手内容也应按当前模型规则处理。第一次排查时，把不必要的参数删掉，回到最小请求，再一项项添加。

六、想逐字看到回答，可以用流式输出

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "解释如何检查数据单位。"}],
    output_config={"effort": "medium"},
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print()
print(final_message.stop_reason)

流式输出改善的是接收过程，不会自动提高回答质量，也不会取消费用和限制。中间已经出现文字，也并不表示后面一定不会报错；应确认最终状态后再保存为成功结果。

七、怎样判断调用真的完成？

普通文字任务返回 end_turn，通常表示这一轮已经结束。遇到 max_tokens，检查是否截断；遇到 tool_use，需要程序执行相应工具并继续；遇到拒绝类状态，则查看具体原因。

任务是否完成，还要看业务要求。比如要求列出五项而只返回三项，即使请求正常结束，也不能算符合要求。

八、运行失败先查哪里？

401 先查认证，403 先查权限，404 检查地址和模型名称，400 查看参数与输入内容，429 区分限流和额度问题。服务端临时错误再考虑有限重试。

记录请求 ID、状态码、错误类型和时间，避免只保存一句“调用失败”。不要把真实密钥或完整敏感材料写进错误日志。

把最小调用跑通后，再加入你真正需要的功能。每次增加一个变化，并保留对应的成功请求，出了问题就能快速退回已知可用的版本。