模型与协议
模型 ID 从哪来、哪个模型走哪个端点、Responses 支持度怎么判断、官方 SDK 兼容性与流式开启方式。
1. 找到可用的模型
1.1 怎么知道我能用哪些模型？
调 GET /v1/models。它只返回当前 API Key 已授权、且在账号权限与实际上游路由下仍可用的模型，并给出每个模型的 type、supported_protocols、protocol_endpoints、format 和 endpoint。
原样使用返回的模型 ID。字段含义见模型列表。
1.2 提示 Model not available 怎么办？
三点依次检查：
- 模型 ID 来自当前 API Key 的
GET /v1/models。 - 该模型已授权给这把 Key。
- 该模型所选渠道当前仍可用。
1.3 该发哪个模型 ID？
GET /v1/models 返回的 LLM ID，原样发送。网关会按该模型选定的渠道路由，同一把 Key 的不同模型可以走不同渠道。
2. 选对协议
2.1 为什么用 OpenAI 格式调 Claude、Gemini 会失败？
因为这两家有各自的原生协议，网关按原生协议转发：
| 模型 | 端点 | 说明 |
|---|---|---|
| Claude | POST /v1/messages | 见 Anthropic 格式。走 /v1/chat/completions 会被拒绝 |
| Gemini | POST /v1/models/{model}:generateContent | 见 Gemini 格式 |
例外：supported_protocols 包含 openai-completions 的 Gemini 型号可以用 OpenAI Chat Completions。Claude 没有这个例外。
2.2 怎么判断模型支持 Responses？
调 GET /v1/models，看 supported_protocols 是否包含 openai-responses；旧客户端可以改看 responses_endpoint 是否为 /v1/responses。满足则可用 OpenAI Responses API。
一律以模型列表返回项为准，不要根据模型名判断——/v1/responses 只接受明确声明支持的已开放模型。
2.3 能用官方 OpenAI SDK 吗？
可以，范围是 OpenAI 风格端点：Chat Completions、声明了 responses_endpoint 的模型的 Responses，以及 GPT Image 2 的 generations / edits。
Claude 用原生 SDK。Gemini 默认原生格式，supported_protocols 包含 openai-completions 的型号也可用 OpenAI SDK。通用媒体生成用异步任务 API。
2.4 流式怎么开？
| 协议 | 开启方式 |
|---|---|
| Chat Completions | 请求体传 "stream":true |
| OpenAI Responses | 请求体传 "stream":true |
| Anthropic Messages | 请求体传 "stream":true |
| Gemini | 改用 :streamGenerateContent |
| 媒体模型 | 不使用 SSE，创建任务后轮询状态 |
3. 参数与缓存
3.1 GPT 模型怎么命中提示词缓存？
固定携带 session-id 请求头：从响应中读取该值，在同一关联会话的每次 LLM 请求中原样发送。这个头可选，但建议始终携带。
thread-id 和 conversation-id 只用于会话追踪，不是缓存命中的必需条件。媒体任务端点和其他自定义请求头不会透传，也不要在这些头里放敏感凭据。
3.2 Flex 渠道的 claude-opus-4-7 / 4-8 报 400 怎么办？
这两个 Flex 模型对采样参数较严格：
temperature固定填1.0，或者不传。- 不要同时传
temperature和top_p。
需要其他取值时，把该模型的渠道改成 Standard，继续用同一个模型 ID。