选择协议
| 需求 | 推荐入口 | 返回结构 |
|---|---|---|
| 新应用、Responses 工具项目、多模态输入或推理控制 | POST /v1/responses | object: response，结果在 output |
现有应用依赖 messages、choices 或 Chat SSE | POST /v1/chat/completions | choices[] |
| 需要厂商原生 Messages / Gemini 字段 | 查看 聊天 API 接入与协议选择 | 按对应原生协议处理 |
Responses 与 Chat Completions 的输入、结果和结束事件不同。即使模型名称相同，也不能直接复制另一种协议的请求体或解析代码。本站当前公开的 Responses 入口为 POST /v1/responses；创建响应后不能通过本目录承诺的 GET、取消或删除接口管理它。
模型与功能边界
模型是否可用取决于你的 API Key、模型权限和当前渠道。先通过 列出当前 Key 可用模型 核对模型，再确认该模型支持你要用的输入、工具或推理字段。兼容层可能转换请求；厂商文档描述的能力不自动代表本站每个模型都开放。
| 任务 | 文档 |
|---|---|
| 文本与基本请求 | 创建 Response |
| 增量输出 | Responses 流式返回 |
| 函数工具往返 | 函数调用与结果回传 |
| 推理或 JSON Schema | 推理强度与结构化输出 |
| 图片与文件输入 | 多模态输入 |
| 网络搜索 | Responses 网络搜索 |
| 从旧示例迁移 | Responses 迁移说明 |
| 上下文压缩 | Responses compact |
鉴权与基础地址
所有示例使用 https://top.qingyuntop.ai 和本站 API Key：Authorization: Bearer YOUR_API_KEY。不要将控制台登录令牌或模型厂商 API Key 用于此请求。SDK 的 base_url 是否包含 /v1 取决于 SDK；原始 HTTP URL 已写完整。
结果与故障处理
非流式请求从 output 按项目类型读取文字、工具调用或其他内容，不能读取 choices[0]。只有 status: completed 表示正常完成；failed 和 incomplete 需读取错误或 incomplete_details。流式请求按 SSE 事件解析，只有 response.completed 是成功终态。客户端超时或断线不表示请求未被处理；不要盲目重复提交。
遇到鉴权、模型权限、限流、格式错误或超时问题，保留模型名、请求时间、响应状态和脱敏错误，按 聊天 API 接入与排错总览 检查。价格和可用额度以控制台显示为准。