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

Responses 函数调用与结果回传

函数调用是由应用控制的多轮请求：模型返回函数名、参数和 `call_id`；你的应用校验并执行函数，再用相同 `call_id` 回传结果。

API Key application/json

功能与适用场景

适合将受控业务能力交给模型选择，例如查询天气或订单状态。函数声明不会在本站替你执行代码；不要把模型生成的 SQL、文件路径、URL 或权限判断直接交给执行器。

支持模型与组合

示例使用 gpt-6-astra 的 Responses 函数工具格式。使用前确认 API Key 可用该模型且上游渠道支持函数调用。天气函数只接受示例城市“北京”，应用必须在执行前检查名称、参数、用户权限和业务幂等性。

第一步：设置鉴权

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

第二步：声明工具并调用模型

发送 POST https://top.qingyuntop.ai/v1/responses。第一次请求包含 input 和 tools；模型可返回普通答案，也可返回一个或多个 function_call 项。

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 项。
  • 函数调用的 arguments 是 JSON 字符串，不是已经解析好的对象。解析、校验并在服务端执行后，再以 function_call_output 输入项继续请求。
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。
toolsarray<object>

function、web_search、file_search 等工具声明；本站是否能路由到对应上游能力取决于模型和渠道。

元素数量：1–∞
元素object
typestring必填

工具类型，如 function 或 web_search；内置工具受模型和渠道能力约束。

namestring

函数工具名称；应与应用实际注册和执行的函数一致。

descriptionstring
parametersstring

定义函数参数的 JSON Schema；应用执行前仍须校验模型返回值。

strictstring

请求严格参数校验；是否受支持取决于模型及上游渠道。

tool_choiceoneOf

auto、none、required 或指定工具。

满足其中一个分支
分支 1string
可选值：auto、none、required
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 项。
  • 函数调用的 arguments 是 JSON 字符串，不是已经解析好的对象。解析、校验并在服务端执行后，再以 function_call_output 输入项继续请求。

第一次请求：声明工具

set -euo pipefail
printf '%s' '{
  "model": "gpt-6-astra",
  "input": "查询北京天气。",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "查询城市天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  ],
  "tool_choice": "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

校验并回传函数结果

在 output 中查找 type: function_call，校验 name 与 arguments，再执行白名单中的函数。第二次请求需把用户输入、模型实际返回的完整函数调用项目和一个 function_call_output 按顺序组成 input；调用 ID 必须与第一轮的 call_id 完全相同。并行调用时，每个函数调用都要对应一条输出。

示例数据明确标为“示例数据”，不代表实时天气。生产应用应处理无函数调用、多个调用、参数无效、业务失败和重复执行。

第二次请求：回传结果

set -euo pipefail
call_id="$(jq -er '.output[] | select(.type == "function_call" and .name == "get_weather") | select((.arguments | fromjson).city == "北京") | .call_id' response.json)"
jq -n --slurpfile request request.json --slurpfile response response.json --arg call_id "$call_id" --arg model "gpt-6-astra" --arg output '{"temperature_c":22,"source":"示例数据"}' '
  {model:$model,
   input:[{role:"user",content:$request[0].input},
     ($response[0].output[] | select(.type=="function_call" and .call_id==$call_id)),
     {type:"function_call_output",call_id:$call_id,output:$output}],
   tools:$request[0].tools}' > next-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 @next-request.json \
  --output next-response.json

结果与错误处理

第二次请求仍返回 Response 对象；检查 status，只在 completed 时处理最终结果。若第一轮没有 get_weather 调用，示例会停止而不会伪造工具成功。工具失败时按你的业务约定回传可识别的失败内容，不要把失败伪装成成功结果。

400：检查函数 schema 与 input 顺序；403：确认模型和工具权限；429：遵循 Retry-After。遇到不确定的网络超时，不要盲目重复执行有副作用的函数。保留两个请求与响应文件，并使用业务幂等键保护写操作。

OpenAI 函数调用指南 · Responses 流式事件