为帮助您更稳妥地集成和使用方舟 API，本文介绍方舟关于向后兼容性的通用说明，以及建议采用的客户端适配方式。
适用范围#
本说明适用于以下对象：
- REST API。
- 方舟官方 SDK。
- 模型系列。
兼容性说明#
方舟会尽量避免在同一主版本中引入不兼容的接口变更，以降低协议演进对存量接入的影响。
模型输出和提示词行为本身具有不确定性，不同模型版本之间的提示词行为和模型表现可能发生变化。如需获得更稳定的模型输出，建议固定模型版本，并结合实际业务场景进行评测与验证。
常见的向后兼容变更#
以下变更通常属于向后兼容的变更：
- 新增 API 接口。
- 新增可选的请求参数。
- 在 JSON 响应对象或事件数据中新增字段。
- 调整 JSON 响应对象中字段的返回顺序。
- 调整资源标识等不透明字符串的长度或格式。
- 在流式 API 中新增事件类型。
客户端适配建议#
为更好地开发后续演进，建议您在客户端开发中遵循以下原则：
- 对响应内容采用宽松解析策略，忽略未识别字段；如非业务必需，不建议对整个响应 JSON 做强校验。
- 对枚举类型字段保留未知值兼容能力，避免因新增取值直接报错。
- 仅传递业务必需的请求参数，不依赖未文档化的参数或行为。
- 基于 HTTP 状态码、错误码等稳定结构处理错误，不依赖错误消息的具体文案。
- 不依赖 JSON 字段顺序，以及资源标识等不透明字符串的固定长度或固定格式。