核心API
模型与能力
模型 ID、协议和能力是三个不同维度。能列出或调用某个模型，不代表它在每种协议下都支持同一组参数。
可用性的权威来源
- 模型广场：查看当前模型 ID、分组、价格和运行状态。
GET /v1/models：查看当前 Key 在接口层可见的模型。- 最小能力测试：用相同 Key、分组、协议和模型逐项验证流式、工具、视觉等生产所需能力。
协议能力矩阵
| 能力 | Responses | Chat Completions | Anthropic Messages |
|---|---|---|---|
| 基础文本 | 公开支持 | 公开支持 | 公开支持 |
| SSE 流式 | 公开支持；事件结构独立 | 公开支持；处理 delta 与结束标记 | 公开支持；处理 Messages 事件生命周期 |
| 函数工具 | 模型与通道条件支持；HTTP 使用无状态回放 | 模型与通道条件支持 | 模型与通道条件支持 |
| 结构化输出 | 模型与 Schema 条件支持 | 模型与 Schema 条件支持 | 不能假定与 OpenAI Schema 字段等价 |
| 图片或文档输入 | 模型、MIME 和输入结构条件支持 | 模型与内容块条件支持 | 模型、MIME 和内容块条件支持 |
| Token 预估 | 根据客户端 tokenizer 估算 | 根据客户端 tokenizer 估算 | POST /v1/messages/count_tokens |
| 服务端状态续接 | 普通 HTTP 不承诺 previous_response_id | 客户端重发历史 | 客户端重发历史 |
“条件支持”表示必须用当前模型和分组验证，不能仅依据模型厂商文档或同名模型推断。具体请求结构见文本 API。
Responses 状态续接
当前普通 HTTP Responses 接入不把 previous_response_id 作为公开兼容保证。多轮工具调用应采用无状态回放：保留原始输入，追加上一轮完整 response.output，再追加工具结果，并重发相同工具定义。
不要只保存文本。推理项、函数调用项、call_id 和工具结果都可能是下一轮所需上下文。使用 Agent SDK 时，也要确认 SDK 是否依赖服务端响应存储。
模型元数据
为 SDK 或编码 Agent 添加自定义模型时，除模型 ID 外还可能需要配置上下文窗口、最大输出、输入模态、推理能力和成本显示。缺失或猜测这些值会造成过早压缩、错误截断或错误能力展示。
- 动态价格和可用分组以模型广场为准，不在客户端配置中硬编码为结算依据。
- 上下文和输出上限应来自当前通道的已验证值；没有确认时使用保守配置。
- 同名模型经不同协议或分组路由时，不承诺与厂商直连具有完全相同的字段和行为。
未纳入公开契约的能力
以下能力不应因为上游软件或模型厂商支持就被视为 KHaiXAPI 已公开支持：Responses WebSocket、Realtime、Embeddings、Audio、Video、原生 Gemini 协议、Hosted Agents、图片批任务及其他未列入当前导航的端点。
如生产业务依赖其中任何一项，请先向支持确认线上是否开放，再以实际 Key 完成端到端测试。未记录的内部路由不构成稳定的公共 API。
上线前验证
- 固定测试条件：记录模型 ID、Key 分组、协议、SDK 版本和测试日期。
- 逐项测试：基础文本、流式、工具、结构化输出、视觉和长上下文分别验证。
- 覆盖失败路径：认证、权限、限流、上游 5xx、流中断开和客户端取消。
- 核对费用：对比协议 usage、控制台用量和实际扣费，不用估算值替代账单。