青云TOP API使用教程&开发文档小白用户&专业开发者快速使用指南
控制台
返回模型调用 API 参考
POST/v1/responses

创建模型响应：流式返回

对 Responses 请求设置 `stream: true` 后，本站返回 SSE 事件；本页说明如何接收事件、识别成功终态，以及如何处理断线或未完成响应。

API Key application/json

适用场景与事件边界

流式适合逐步呈现文本或处理工具/推理项目。一次网络读取可能只含半个 SSE 事件；必须先按空行组装事件，并把同一事件中的多条 data: 行合并后再解析 JSON。

支持模型与组合

示例沿用基础创建页的 gpt-6-astra 格式。请确认当前 API Key 可用该模型，且所选模型/渠道支持 Responses 流式输出。其他请求字段和 创建 Response 相同。

第一步：设置鉴权

使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY，替换占位符并保留 Bearer 后的空格。

第二步：调用模型

发送 POST https://top.qingyuntop.ai/v1/responses，设置 JSON Content-Type，并在请求体添加 "stream": true。成功响应应为 text/event-stream。

Responses API

调用与返回说明

OpenAI 新项目的首选模型调用协议。它以 output 项目表达文本、工具调用和推理结果，不能按 Chat Completions 的 choices 结构读取。

请求时注意

  • 模型 ID 不要从示例中照抄。先调用 GET /v1/models，再选择返回列表中实际可用且支持当前协议的完整 ID。
  • Responses API 的 input 可以是字符串，也可以是带 role/content 的输入项目数组；图片、文件和工具调用必须使用官方规定的输入项目类型。
  • 不要把 Chat Completions 的 choices、message 或 delta 结构混用于 Responses API。

返回时注意

  • 先检查 HTTP 状态码，再检查 response.status。只有 status=completed 才应视为完整成功；incomplete、failed 等状态必须进入业务失败或补偿流程。
  • 文本优先读取 SDK 的 response.output_text；直接 HTTP 客户端应遍历 output，并提取 message 内容中的 output_text 项。
  • 流式结束以 response.completed 等事件为准；同时处理 response.failed、response.incomplete 和网络断开，不要只等待 [DONE]。
Request

请求

/v1/responses

Body

必填
Bodyapplication/json
Bodyobject
modelstring必填

模型 ID。本站账号可用模型以模型列表和实际权限为准；示例使用 gpt-6-astra。

示例gpt-6-astra
inputoneOf必填

文本或输入项目数组；数组可包含 user/developer 消息、input_text、input_image、input_file。

满足其中一个分支
分支 1string
示例用一句话介绍青云TOP API。
streamboolean

设为 true 返回 SSE；网络分块不等于完整事件。

示例true
Response

返回响应 200

成功响应
响应 200application/json
响应 200object
idstring必填

响应唯一标识。需要关联或排查请求时保存它。

示例resp_...
objectstring必填

固定为 response。不要用 choices 判断 Responses API 的返回。

固定值：response
statusstring必填

响应状态，常见值包括 completed、incomplete、failed、in_progress。业务成功判定应检查此字段。

可选值：queued、in_progress、completed、failed、incomplete
modelstring

实际使用的模型 ID。

示例gpt-6-astra
outputarray<oneOf>必填
元素array<object>

输出项目数组，可能包含 message、function_call、reasoning 等不同类型。

满足其中一个分支
分支 1object
idstring

响应唯一标识。需要关联或排查请求时保存它。

示例msg_...
typeunknown必填
固定值：message
roleunknown必填
固定值：assistant
contentarray<object>必填
元素object
typeunknown必填
固定值：output_text
textstring必填
annotationsarray<object>
元素object
errorobject|null

失败信息。HTTP 200 仍可能对应 failed 或 incomplete 状态，必须同时检查此字段。

incomplete_detailsobject|null

响应未完成时的原因和细节。

usageobject

token 用量，通常包含 input_tokens、output_tokens、total_tokens 及其 details。

input_tokensinteger
output_tokensinteger
total_tokensinteger
Responses API

调用与返回说明

OpenAI 新项目的首选模型调用协议。它以 output 项目表达文本、工具调用和推理结果，不能按 Chat Completions 的 choices 结构读取。

请求时注意

  • 模型 ID 不要从示例中照抄。先调用 GET /v1/models，再选择返回列表中实际可用且支持当前协议的完整 ID。
  • Responses API 的 input 可以是字符串，也可以是带 role/content 的输入项目数组；图片、文件和工具调用必须使用官方规定的输入项目类型。
  • 不要把 Chat Completions 的 choices、message 或 delta 结构混用于 Responses API。

返回时注意

  • 先检查 HTTP 状态码，再检查 response.status。只有 status=completed 才应视为完整成功；incomplete、failed 等状态必须进入业务失败或补偿流程。
  • 文本优先读取 SDK 的 response.output_text；直接 HTTP 客户端应遍历 output，并提取 message 内容中的 output_text 项。
  • 流式结束以 response.completed 等事件为准；同时处理 response.failed、response.incomplete 和网络断开，不要只等待 [DONE]。

事件处理与完成判断

事件处理方式
response.created、response.in_progress记录响应 ID 和处理中状态
response.output_text.delta将增量文字追加到当前消息
response.output_item.added、response.output_item.done按项目类型处理消息、工具或推理项目边界
response.completed成功终态；保存其完整 response 对象和用量
response.failed、response.incomplete、response.cancelled、error非成功结束；保存事件及错误详情供排查

不要把 response.output_text.delta 当作完整 Response，也不要把 [DONE]（若上游发送）单独当作业务成功。示例将事件保存在 events.json；确认成功后从终态读取 response。连接中断、客户端超时或 incomplete 不会自动取消请求；本站此入口没有公开的按 ID 查询/恢复接口，避免盲目重复提交。

常见错误与参考

若 Content-Type 不是 SSE，先按 HTTP 状态读取错误正文；若流结束却没有 response.completed，保留 events.json、响应 ID、模型、时间和脱敏错误，再联系支持。不要将一次 TCP chunk 直接交给 JSON parser。

Responses 流式事件

流式事件示例

下面只展示事件形状。生产客户端应按事件类型处理增量、完成、失败和未完成事件，并设置读取超时。

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"你好","item_id":"msg_example","output_index":0,"content_index":0}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_example","status":"completed","output":[]}}