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

创建模型响应

使用本站 `POST /v1/responses` 发送文本或内容项目，直接取得 Responses 格式的响应对象；本页从鉴权、提交到判断完成串起一次非流式调用。

API Key application/json

功能与适用场景

适用于文本生成、问答和后续 Responses 工具页所需的基础请求。input 可为文本或消息/内容项目数组；图片、文件、搜索和工具的字段组合见各专题页，不要只因字段出现在官方 schema 就假定当前模型支持。

支持模型与组合

model 必填。示例以 gpt-6-astra 演示本站 Responses 请求格式；实际发送前，请用当前 API Key 查询模型列表并确认模型支持 Responses。视觉、推理与工具能力按具体模型和渠道确认。

第一步：设置鉴权

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

在 HTTPS 请求头中携带 API Key；不要将厂商 Key 放入请求。

第二步：调用模型

发送 POST https://top.qingyuntop.ai/v1/responses，并设置 Content-Type: application/json。完整请求可直接运行；示例保存请求和响应，供排错或本目录后续工具示例读取。

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。
instructionsstring

作为开发者指令加入本次上下文；与 previous_response_id 一起使用时不会自动继承上一轮指令。

streamboolean

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

示例true
storeboolean

是否请求上游保存响应；本站不承诺保存期限或所有渠道都接受该字段。

示例false
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]。

常见错误与参考

400：核对 JSON 类型、必填 model/input 和模型支持的参数；401：检查本站 API Key 与 Bearer 格式；403：确认模型权限；429：遵循 Retry-After 并退避。若客户端超时或收到 5xx，不要直接重复有副作用的请求；记录请求时间、模型和脱敏错误后再决定是否重试。

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":[]}}