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

火山方舟