Anthropic SDK v1.15.0 更新：Messages API 新增速度参数

Anthropic 官方 SDK 发布了 v1.15.0 版本，这次更新幅度不大，但几处 API 层面的改动值得开发者留意。

核心变更：Messages API 引入 speed 参数

本次更新最值得关注的是 Messages API 新增了 speed 参数，同时响应体中加入了 usage.speed 字段。这意味着开发者可以在请求层面直接控制模型输出的速度模式，而不需要依赖额外的配置或变通方案。

从 SDK 的文档说明来看，部分模型需要通过 beta header 才能启用 speed 功能，这一点在实际接入时需要特别注意。SDK 层面已经为不同模型的 capabilities 做了适配，开发者可以通过 between_tools 字段在 thinking types 中判断模型是否支持该能力。

这种设计思路延续了 Anthropic 在模型能力声明上的一贯做法——把模型支持的特性暴露在 API 的 capabilities 描述中，让客户端可以动态适配，而不是硬编码判断逻辑。

关于 beta header：Anthropic 的 API 长期采用 beta header（形如 anthropic-beta: xxx-2024-xx-xx）机制来发布尚未稳定的功能。之所以不是所有模型都直接支持 speed，是因为该能力需要在推理侧调整调度策略，只有部分新版本模型才具备。客户端在发请求时，需要在 HTTP header 中显式声明对应的 beta 标识，服务端才会解析 speed 字段；否则该参数会被忽略或直接报错。Anthropic 通常在功能稳定后会把 beta 能力转正，届时 header 声明即可移除。因此在使用前，建议先通过模型 capabilities 接口确认目标模型是否已原生支持。

关于 usage.speed 与 capabilities 判断：usage 字段在 Messages API 中一直用于返回本次调用的 token 统计（如 input_tokens、output_tokens）。本次新增的 usage.speed 用于回显服务端实际采用的速度模式，便于在日志或计费体系中区分不同速度档位的调用。而 capabilities 中的 between_tools 字段，指的是模型在 thinking（思维链）环节中，是否支持在多次工具调用之间穿插思考过程。把这类细粒度能力暴露在 capabilities 里，可以让客户端在运行时动态决定是否启用相关参数，避免因硬编码判断导致在不同模型上出现调用失败。

组织级消费限额：只读的 spend limit

另一个 API 层面的变化是，Console 组织的 usage-tier 消费上限现在会以只读的 spend limit 形式返回。

这个改动的实际意义在于，开发者可以通过 API 直接读取当前组织的消费限额信息，而不需要登录 Console 手动查看。对于需要做成本监控和自动告警的团队来说，这省去了不少麻烦。不过目前是只读属性，无法通过 API 修改限额。

关于 usage-tier 与 spend limit：Console 中的 usage-tier 指的是组织按累计消费划分的等级，不同等级对应不同的速率限制和功能权限。spend limit 则是组织或工作区设定的消费上限，达到阈值后 API 调用会被拒绝，用于防止账单意外超支。此前这些数值只能在 Console 界面查看，程序难以自动化获取。改为通过 API 只读返回后，团队可以在监控系统中定期拉取限额与当前用量，结合告警规则提前预警。需要注意，只读意味着通过 API 无法调整限额，配置仍需在 Console 完成。

工程与文档层面的改进

除了面向开发者的 API 变更，这次版本还包含若干内部改进：

CI 加速：breaking change 检测流程做了提速优化。对于频繁发版的 SDK 项目来说，CI 环节的时间成本会直接影响迭代节奏。

文档补充：Managed Agents 和 telemetry 端点的 headers 说明得到了完善，同时简化了 docs 中格式化代码块的脚本。SDK 文档中关于 speed 参数需要 beta header 的说明也一并补充了进去。

测试覆盖：新增了对 OpenTelemetry 选项和方法默认超时的测试用例。超时行为的测试覆盖对于 SDK 稳定性来说很关键，尤其是在网络环境复杂的生产场景下。

关于 OpenTelemetry 与默认超时测试：OpenTelemetry 是一套厂商中立的可观测性标准，涵盖 trace、metrics 和 logs。SDK 支持 OpenTelemetry 后，开发者可以把 API 调用的耗时、重试、错误等信息接入既有的观测管道，与业务链路统一分析。方法默认超时则决定了单次请求在无响应时等待多久后放弃，超时设置过短会误杀慢请求，过长则会让故障请求长时间占用连接。为这两项行为补充测试用例，本质上是把原本隐式的默认行为固化为可回归验证的契约，降低未来重构引入隐性破坏的风险。

对开发者的实际影响

如果你的项目已经在使用 Anthropic Messages API，这次升级基本是平滑的——新增参数都是可选的，不存在破坏性变更。

真正值得尝试的是 speed 参数带来的灵活性。在一些对延迟敏感的场景（比如实时对话、流式输出），能够按请求粒度调整速度模式，比全局配置要实用得多。建议先确认目标模型是否需要 beta header，再决定是否在 capabilities 判断逻辑中加入相应分支。

消费限额的只读暴露则更适合已经在做成本管理的团队，可以把它接入现有的监控管道。

总体来看，v1.15.0 是一个以 API 能力扩展和工程打磨为主的常规版本，没有激进的变化，但对深度使用 Messages API 的开发者来说，几处小改动都能落到实处。