POST/v1/responses

Responses 推理强度与结构化输出

为支持的模型设置 Responses 推理选项，或要求输出符合 JSON Schema 的 JSON；两者是不同配置，字段需放在各自对象中。

API Key application/json

功能与适用场景

reasoning 用于支持推理的模型；text.format 用于约束输出格式。并非每个模型、兼容渠道或 Responses 转换路径都接受相同字段，遇到参数错误时先删去可选项验证基础请求。

支持模型与组合

示例使用 gpt-6-astra 的 Responses 字段格式。先确认该模型和当前渠道支持相应能力；effort 值不是跨模型通用保证。不要将思考摘要当作模型的完整内部推理过程。

第一步：设置鉴权

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

第二步：设置参数并调用模型

两种示例都使用 POST https://top.qingyuntop.ai/v1/responses，每次只演示一种配置，便于分别排查字段支持。

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。

reasoningobject

effortstring

none、minimal、low、medium、high、xhigh、max；可用值取决于模型。

可选值：none、minimal、low、medium、high、xhigh、max

示例medium

summarystring

auto、concise 或 detailed；是否支持取决于具体模型。

可选值：auto、concise、detailed

示例auto

textobject

formatobject

text、json_object 或 json_schema 等结构化输出格式，必须符合模型能力。

typestring必填

text、json_object 或 json_schema；选择 json_schema 时还需提供 format.name、format.schema 与 format.strict。

可选值：text、json_object、json_schema

示例json_schema

nameobject

json_schema 格式名称；与 schema 一起放在 text.format 中。

schemaobject

输出 JSON Schema；对象结构与字段约束由应用定义，并在收到结果后再次验证。

示例{"type":"object","properties":{},"additionalProperties":false}

strictobject

是否请求严格遵循 JSON Schema；模型/渠道不支持时可能报错。

请求示例application/json

set -euo pipefail
printf '%s' '{
  "model": "gpt-6-astra",
  "input": "比较两个方案的优缺点。",
  "reasoning": {
    "effort": "medium",
    "summary": "auto"
  }
}' > request.json
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

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

推理参数

set -euo pipefail
printf '%s' '{
  "model": "gpt-6-astra",
  "input": "比较两个方案的优缺点。",
  "reasoning": {
    "effort": "medium",
    "summary": "auto"
  }
}' > request.json
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

JSON Schema 输出

set -euo pipefail
printf '%s' '{
  "model": "gpt-6-astra",
  "input": "从“北京现在22摄氏度”提取城市和温度。",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "weather",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "temperature_c": {
            "type": "number"
          }
        },
        "required": [
          "city",
          "temperature_c"
        ],
        "additionalProperties": false
      }
    }
  }
}' > request.json
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

常见错误与参考

若模型拒绝某个 effort 或格式字段，先确认其能力表和渠道支持，再逐项精简请求；不要将被忽略或上游拒绝的字段描述为已生效。

OpenAI 推理指南 · Responses 文本格式

Responses 推理强度与结构化输出

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：设置参数并调用模型

调用与返回说明

请求时注意

返回时注意

请求

Body

返回响应 200

调用与返回说明

请求时注意

返回时注意

推理参数

JSON Schema 输出

常见错误与参考

返回响应 `200`