破坏性变更政策

概述

为了平衡快速开发与稳定性维护，ElevenLabs 针对 API 范围内哪些变更属于破坏性变更制定了具体指南。以下说明哪些变更属于或不属于破坏性变更。

响应和架构变更

我们严格区分 API 响应的新增和删减变更。向响应模型添加新字段不属于破坏性变更。集成 API 时，API 客户端必须忽略无法识别的字段，且不得对 API 响应进行严格类型检查。几乎所有现代 API 客户端默认都具备这一行为。

删除现有响应字段或修改其结构属于破坏性变更，因为客户端应用可能依赖这些字段的存在及其预期格式。

参数修改

API 参数变更遵循严格的兼容性模型。为现有端点添加必填参数始终属于破坏性变更，因为现有客户端调用将无法通过验证。但添加可选参数（具有默认值或明确标记为可选的参数）不属于破坏性变更，因为现有客户端调用无需修改即可继续运行。同样，修改参数类型或格式，或将此前可选的参数设为必填，也都属于破坏性变更，因为这会改变客户端预期的约定。

端点和路径变更

移除整个端点或 API 路径本质上属于破坏性变更，因为调用这些端点的客户端应用将收到错误。端点可能会被标记为已弃用，但在充分通知所有受影响用户之前，不会直接将其移除。