API 接入

Responses API

文本、工具、图片、PDF 和流式输出

端点与鉴权

POST https://www.yunqiai.chat/v1/responses

请求头为 Authorization: Bearer <API_KEY> 和 Content-Type: application/json。model 填写要使用的完整模型 ID。

请求字段

字段	类型	说明
model	string，必填	完整模型 ID
input	string 或 array，必填	单条文本，或完整的消息与工具结果序列
instructions	string	本次请求的顶层指令；需要沿用时在后续请求中再次传入
max_output_tokens	integer	推理及可见输出的总预算；小预算可能只有推理没有正文
reasoning.effort	string	推理强度，可用值见对应型号页
tools	array	函数工具定义，`type=function`，名称及 JSON Schema
tool_choice	string 或 object	`auto`、`none`、`required` 或命名函数；需匹配型号支持范围
text.format	object	结构化输出定义，如 `type=json_schema`
stream	boolean	true 时返回 SSE，不是单个 JSON

temperature、top_p、top_logprobs 是否可用取决于模型和推理模式。Responses 的输出预算和格式分别使用 max_output_tokens、text.format，不使用 Chat 的 max_tokens、response_format。

json

{
  "model": "gpt-6-astra",
  "input": [{"role":"user","content":[{"type":"input_text","text":"仅回复 READY"}]}],
  "reasoning": {"effort":"low"},
  "max_output_tokens": 2048
}

示例中的模型 ID 可替换为要使用的 Responses 型号。

读取响应

先检查 status、error 和 incomplete_details，再遍历 output[]。正文位于 type=message 的 content[]，读取其中 type=output_text 的 text。推理项、拒绝内容和 function_call 分别处理，不并入普通正文。

status=incomplete 表示生成未完成。保存已有内容，并按 incomplete_details.reason 处理。增加预算后重新调用属于新请求，可能产生额外消耗，应限制重试次数。HTTP 200 但没有所需文本或工具调用时，也需按异常结果处理。

工具与多轮

定义函数时使用 {"type":"function","name":"lookup","description":"...","parameters":{"type":"object","properties":{},"additionalProperties":false},"strict":true}。严格模式的对象字段需要满足对应 JSON Schema 约束。

收到 function_call 后：

保存整个 output 序列，包括推理项。
校验函数名和 JSON 参数，仅执行已允许的本地工具。
将历史输入、原 output、{"type":"function_call_output","call_id":"原 call_id","output":"工具结果字符串"} 一起作为后续 input。
同轮多个调用逐一回传，结果中的 call_id 对应原调用的 call_id，而非 id。

对话历史由应用保存并随请求传入，此写法不依赖 previous_response_id 或 store。自定义函数调用与内置网页检索、文件检索、代码解释器是不同功能，后者需单独确认支持情况。

图片与文件

图片消息内容块为 {"type":"input_image","image_url":"data:image/png;base64,<BASE64>"}。可在同一 content 数组放入多张图片，每张单独一个内容块。

PDF 内容块为 {"type":"input_file","filename":"brief.pdf","file_data":"data:application/pdf;base64,<BASE64>"}。在同一消息中保留任务文本，返回后可用文件内的标识、页码或数据核对回答。此字段用于文件理解，不用于生图或图片编辑。

DOCX、XLSX、TXT、CSV、JSON 同样使用 input_file，filename 和 data URI 的 MIME 与文件类型保持一致。DOCX MIME 为 application/vnd.openxmlformats-officedocument.wordprocessingml.document，XLSX 为 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet。非 PDF 文件的内嵌图片、图表和版式不保证可读取；需要理解版式时，先转换成 PDF。处理电子表格时，请说明工作表、列名、行范围和计算口径。

file_data 与 image_url 是不同字段，均不能填写本地磁盘路径。此端点暂不提供稳定的音频、视频内联输入，见媒体输入。

流式输出

SSE 按空行分帧，同一帧的多行 data: 合并后再解析 JSON。需要处理 response.output_text.delta、函数参数增量、response.completed、response.incomplete、response.failed 和 error。网络断开时若未收到结束事件，请按中断处理。

完整示例见 Python 请求程序，包含 HTTP 错误正文读取、结束状态检查，且不自动重发 POST。