POST/v1/responses

Responses 图片与文件输入

在 Responses `input` 消息的 `content` 数组中组合文字、图片或文件；本站会按 Responses 结构转发/转换，最终可用格式仍取决于模型和渠道。

API Key application/json

功能与适用场景

图片适合视觉问答；文件适合读取受支持的文档。一次请求可把说明文字和素材放在同一个 user 消息中。本站此目录没有公开 Files 上传/管理 API 教程；不能把本地路径当作 file_id，也不要假设任意模型都能读取任意媒体。

支持模型与输入方式

示例采用 gpt-6-astra 作为字段格式样例。提交前确认模型有对应视觉或文件输入能力，并确认渠道允许该素材。可使用公开可读取 URL 或 data URL；file_id 仅适用于上游已存在且当前渠道可识别的文件 ID。

类型	Responses 内容项	说明
图片	`input_image` 配 `image_url` 或 `file_id`	`detail` 可按模型支持设置；URL 必须能由上游访问
文件	`input_file` 配 `file_url`、`file_data` 或 `file_id`	需要时提供 `filename`；检查 MIME、编码与大小

第一步：设置鉴权

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

第二步：调用模型

发送 POST https://top.qingyuntop.ai/v1/responses，设置 JSON Content-Type。Base64 应使用完整 data:<mime>;base64,... URL 或该协议规定的 file_data 格式，不要把原始 Base64 直接冒充网络 URL。

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。

请求示例application/json

set -euo pipefail
printf '%s' '{
  "model": "gpt-6-astra",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "描述这张图片。"
        },
        {
          "type": "input_image",
          "image_url": "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?auto=format&fit=crop&w=800&q=80",
          "detail": "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": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "描述这张图片。"
        },
        {
          "type": "input_image",
          "image_url": "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?auto=format&fit=crop&w=800&q=80",
          "detail": "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

PDF 文件输入

set -euo pipefail
printf '%s' '{
  "model": "gpt-6-astra",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "概括这个 PDF。"
        },
        {
          "type": "input_file",
          "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf"
        }
      ]
    }
  ]
}' > 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

常见错误与参考

401：检查本站 API Key；400/415：检查内容项类型、MIME 与 URL/data URL 结构；413：缩小素材或按模型限制拆分；403：确认模型与渠道支持该类型。仅发送你有权处理的素材。

OpenAI 图片输入指南 · OpenAI 文件输入指南 · 创建 Response

Responses 图片与文件输入

功能与适用场景

支持模型与输入方式

第一步：设置鉴权

第二步：调用模型

调用与返回说明

请求时注意

返回时注意

请求

Body

返回响应 200

调用与返回说明

请求时注意

返回时注意

图片理解

PDF 文件输入

常见错误与参考

返回响应 `200`