POST/v1/responses

从旧 Responses 示例迁移

本页用于修正旧页面中混入 Chat Completions 结构的示例，并说明怎样将应用迁到本站当前公开的 Responses 创建入口。

API Key application/json

适用范围

本站公开的 Responses 创建调用为 POST /v1/responses；compact 为按模型/渠道条件开放的独立入口。此目录没有确认公开的 Response GET、取消、删除或 Files 管理入口。OpenAI 官方支持某个端点，不代表本站也开放该端点。

本页旧 URL 保留供已有书签和链接迁移使用。需要从零开始调用，请直接阅读创建 Response。

请求和响应差异

项目	Responses	Chat Completions
输入	`input`	`messages`
文本输出	`output` 中 message/content 的 `output_text`	`choices[].message.content`
函数请求	`function_call` 项与 `call_id`	`tool_calls[]` 与其 `id`
工具结果	`function_call_output`，匹配 `call_id`	`role: tool`，匹配 `tool_call_id`
流式终态	`response.completed` 等事件	结束原因与可选 `[DONE]`

不要把 Chat 的 choices、finish_reason 或 tool_call_id 混进 Responses 示例。

迁移步骤

将消息历史按 Responses 支持的角色和内容项目转为 input。
保留 Responses output item 类型；从 message 的 output_text 取文字，不把推理/工具项目拼入用户正文。
工具调用时执行白名单校验，并用原始 call_id 回传 function_call_output。
流式请求使用 SSE 事件并以 response.completed 判断成功；不要复用 Chat 的 delta/结束解析器。
删除旧示例中的 metadata.model_id 等非请求必需字段，使用 model；模型名和功能按当前 Key 的列表与权限确认。

鉴权与下一步

本站请求使用 Authorization: Bearer YOUR_API_KEY，地址为 https://top.qingyuntop.ai。替换占位符并保留 Bearer 后的空格，不要使用厂商 API Key。需要逐步输出时见Responses 流式返回。

Responses 与 Chat Completions 对比 · OpenAI Responses API

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

Request

请求

/v1/responses

Body

必填

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 一起使用时不会自动继承上一轮指令。

previous_response_idstring

用于多轮状态；仅在上游/渠道保留 Responses 状态时可用，失败时改用完整 input 历史。

请求示例application/json

curl -X POST https://top.qingyuntop.ai/v1/responses \
  -H "Authorization: Bearer ${QINGYUN_TOP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6-astra",
  "input": "",
  "instructions": "",
  "previous_response_id": ""
}'

Response

返回响应 `200`

成功响应

响应 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

响应示例application/json

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1710000000,
  "status": "completed",
  "model": "MODEL_ID_FROM_V1_MODELS",
  "output": [
    {
      "type": "message",
      "id": "msg_example",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "你好，我可以帮助你。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 12,
    "total_tokens": 30
  }
}

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

从旧 Responses 示例迁移

适用范围

请求和响应差异

迁移步骤

鉴权与下一步

调用与返回说明

请求时注意

返回时注意

请求

Body

返回响应 200

调用与返回说明

请求时注意

返回时注意

返回响应 `200`