指南
本节说明跨 API 家族的请求行为，包括流式传输、工具调用、结构化输出、提示缓存和模型回退。
当你已经知道要调用哪个 API 家族，但需要把接入做成可上线的生产集成时，阅读本节。这里说明跨路由家族的行为：流式传输、结构化输出、工具调用、提示缓存和回退规划。
如果要接入 Claude Code、Codex、Gemini CLI 或其他现成 Agent 产品，请从 Agent 接入 开始。
如果需要精确请求字段，请始终回到 API 参考。指南解释模式，API 页面定义公开合同。
按行为选择
| 需求 | 页面 |
|---|---|
| 从高层理解功能集合 | 概览 |
| 在生成过程中把部分输出返回给用户 | 流式传输 |
| 让模型返回更可预测的 JSON 类输出 | 结构化输出 |
| 让模型调用函数或工具 | 工具调用 |
| 在路由支持时复用较长的提示词前缀 | 提示缓存 |
| 在模型路径失败时保持生产工作负载可用 | 模型回退 |
推荐生产验证顺序
| 阶段 | 要验证什么 | 相关页面 |
|---|---|---|
| 第一条请求 | 密钥、base URL、模型 ID 和最小文本响应 | 验证你的集成 |
| 用户体验 | UI 需要增量片段还是完整响应 | 流式传输 |
| 机器可读输出 | 下游代码是否能安全解析模型响应 | 结构化输出 |
| 外部动作 | 模型是否需要调用由你的应用控制的函数或工具 | 工具调用 |
| 成本和延迟 | 重复提示词前缀是否可以复用 | 提示缓存 |
| 可靠性 | 主模型或供应商路径失败时如何处理 | 模型回退 |
API 家族会影响实现
这些指南说明的是模式，不是所有接口都通用的请求字段。上线生产客户端前，请始终回到 API 参考 确认准确的请求体形状。
| API 家族 | 常见指南关注点 | 哪些地方会变化 |
|---|---|---|
| OpenAI 兼容 | 首次接入、流式、结构化输出、工具调用 | 使用 OpenAI 风格的 messages、stream 和 tool 字段 |
| Anthropic 兼容 | Claude 风格内容块和图片输入 | 使用 Anthropic 请求头和 content block 形状 |
| Gemini 兼容 | Gemini 原生生成、流式和函数声明 | 使用 contents[].parts[] 和 generateContent 等 route method |
| 媒体和音乐 API | 异步任务、轮询、回调和输出 URL | 创建响应可能返回 task ID，而不是最终资产 |
你自己的应用也应记录
对每个生产工作负载，在代码旁保留一份简短接入说明，至少记录：
- 主 API 家族和 route。
- 模型 ID 来源和刷新流程。
- 请求是同步、流式，还是基于任务。
- 重试和回退行为。
- 鉴权、额度、无效请求和临时上游失败时展示给用户的错误信息。