# API 兼容性升级公告

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

发布日期：**2026 年 9 月 9 日**

为降低接入成本并提升协议兼容性，方舟预计将于 **2026 年 9 月 9 日** 陆续对部分 API 的出入参结构和兼容行为进行升级，具体如下。

|升级点 |涉及 API |简要说明 |
|---|---|---|
|`logprobs`、`top_logprobs` 参数支持 |Chat API |* 升级前：API 不支持传入 `logprobs`、`top_logprobs`。 | \
|||* 升级后：DeepSeek V4 正式版系列、GLM-5.2 将支持 `logprobs`、`top_logprobs` 传入和输出。 |
|`developer` 类型 `role` 支持 |Chat API |* 升级前：当 `content` 的 `role=developer` 时会返回报错。 | \
|||* 升级后：将兼容 `role=developer` 输入，不再报错。 |
|Responses API 默认输出加密后的思考内容 |Responses API |* 升级前：如需返回 `reasoning.encrypted_content`，需在请求中显式传入 `"include": ["reasoning.encrypted_content"]`。 | \
|||* 升级后：当模型产生思考内容时，将默认返回 `reasoning.encrypted_content`，无需显式传参。 |
|Responses API 输出格式规范化升级 |Responses API |* 升级前：流式输出中部分字段无有效内容时会省略返回。 | \
|||* 升级后： | \
|||  * `response.created`、`response.in_progress` 事件将新增 `status` 和 `output` 字段返回；无内容的场景下则为空数组。 | \
|||  * `response.output_item.added` 事件中，`reasoning` item 将新增 `summary` 字段返回，`message` item 将新增 `content` 字段返回；无内容的场景下则为空数组。 |
|原生 `web_search` 工具调用能力支持 |Responses API |* 升级前：API 不支持内置的联网搜索能力。 | \
|||* 升级后：方舟 API 将支持原生 `web_search` 工具调用，并支持搜索事件和结果回传。 |
|在 codex 场景下新增对 `phase=commentary`、`final_answer` 的支持 |Responses API |* 升级前：API 无法兼容 `phase` 字段。 | \
|||* 升级后：codex 场景下，API 将新增对 `phase` 字段输入和输出的支持。 |
|`usage` 中新增返回 `cache_creation_input_tokens` 字段 |Messages API |* 升级前：`usage` 中不返回 `cache_creation_input_tokens` 字段。 | \
|||* 升级后： | \
|||  * 返回的 `usage` 中将新增 `cache_creation_input_tokens` 字段。 | \
|||  * 在不涉及该计费场景时，该值返回 `0`。 |
|DeepSeek 系列 `stop`、`stop_sequence` 数组上限由 4 个提升至 16 个 |Chat API<br>Messages API |* 升级前：DeepSeek 系列支持的 `stop`、`stop_sequence` 数组上限为 `4` 个，配置超过 `4` 个会报错。 | \
|||* 升级后：该上限将提升至 `16` 个。 |
|不支持模态内容输入的报错容忍 |Chat API<br>Responses API<br>Messages API |* 升级前：模型收到自身不支持的模态输入时会直接报错并拒绝请求。 | \
|||* 升级后：GLM-5.2、DeepSeek V4 正式版系列收到图片、视频或音频等非模型支持模态时，不再直接报错。 |
|请求输入无法解析的 `encrypted_content`、`signature` 不再报错 |Chat API<br>Responses API<br>Messages API |* 升级前：API 接收到无法解析的 `encrypted_content`、`signature` 时会直接报错。 | \
|||* 升级后：将兼容无法解析的 `encrypted_content`、`signature` 内容输入，不会直接报错。 |
|请求输入的 `content` 为部分非法内容时不再报错 |Chat API<br>Responses API<br>Messages API |* 升级前：API 接收到 `content` 为 `null`、空等非法内容输入时会直接报错。 | \
|||* 升级后：将兼容部分场景的非法 `content` 输入，不会直接报错。 |
|`tool_call_id` 为空时不再报错 |Chat API<br>Messages API |* 升级前：API 接收到 `tool_call_id` 为 `null`、空字符串等非法输入时会直接报错。 | \
|||* 升级后：将兼容部分场景的非法 `tool_call_id` 输入，不会直接报错。 |