OpenAI Responses

官方文档：Create a model response · Text generation · Streaming responses

POST /v1/responses 是 Responses API 形状的文本入口，也是新项目的推荐起点。它用 input 统一承载单轮与多轮内容，输出为结构化的 output 数组。

项目	值
端点	`POST /v1/responses`
Base URL（OpenAI SDK）	`https://api.modelgo.com/v1`
鉴权	`Authorization: Bearer $MODELGO_API_KEY`
协议声明	`openai_responses`

请求示例

bash

curl https://api.modelgo.com/v1/responses \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "input": "用三句话介绍 ModelGo。",
    "max_output_tokens": 256
  }'

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MODELGO_API_KEY"],
    base_url="https://api.modelgo.com/v1",
)

resp = client.responses.create(
    model="<model>",
    input="用三句话介绍 ModelGo。",
)
print(resp.output_text)

常用字段

字段	说明
`model`	平台逻辑模型名
`input`	字符串（单轮），或输入项数组（消息、`function_call`、`function_call_output` 等）
`instructions`	系统提示词，等价于 Chat Completions 的 `system` 消息
`max_output_tokens`	输出上限，最小 16；小于 16 时网关抬到 16（只会多生成，不会少）
`tools` / `tool_choice`	函数工具定义与选择策略
`text.format`	结构化输出格式（如 `json_schema`）
`reasoning.effort`	推理强度，具体取值取决于模型
`stream`	为 `true` 时以 Typed SSE 事件流返回

上游转译边界

网关在入口处就完成模型名解析与协议判定，之后按选中的上游能力选择投递方式：

上游原生支持 Responses 时，请求按 Responses 语义直接转发，previous_response_id、推理摘要等 Responses 专有能力得以保留。
上游只有 Chat Completions 时，网关把请求转译成对话补全再投递，并把返回结果反向映射成 Responses 形状。这一路径会丢弃并记录聊天上游无法表达的能力（例如托管工具、include=reasoning.encrypted_content）。
previous_response_id 的上下文在 24 小时内可被还原；超出窗口或上游不支持时按新请求处理。

因此客户端看到的始终是 Responses 形状，不必关心本次请求落到了哪家上游。

响应与流式

非流式返回 object: "response"，output 是数组（可能同时含 reasoning 与 message 项），文本可从 output_text 读取，用量在 usage。

流式返回 Typed SSE：以 response.created 开始，文本增量是 response.output_text.delta，结束时发 response.completed（带最终 usage）。网关同样会向内层上游强制打开用量回报，保证流式调用按实际用量结算。

关键约定

逻辑模型未声明 openai_responses 协议时，本入口返回 HTTP 400、error_class=model_protocol_not_offered（app_error_id=4005）。
错误信封是 OpenAI 形状：{"error":{...}}，并带顶层 trace_id。
请求体上限 10 MiB。
客户端自带的网关私有字段会在转发前剥离，避免污染上游请求体。

和 Chat Completions 的取舍见文本生成总览：两者能力高度重叠，差别主要在输入形状、事件流与 Responses 专有能力；已有 OpenAI 对话补全代码的客户端不必为此迁移。