OpenAI Responses

兼容 OpenAI 官方 Responses API：POST /v1/responses。相比 Chat Completions，Responses 更适合多轮对话、工具调用、推理模型（o 系列）等场景，并支持响应链式延续。

WARNING

建议使用官方原生接口。Responses API 是 OpenAI 原生新接口，主要服务于 GPT / o 系列模型。若通过本接口调用非 OpenAI 模型（如 Claude、Gemini），由代理侧进行格式转换，可能存在参数缺失或行为差异等问题。具体支持范围请咨询 FreeAPI。

请求

Endpoint

POST https://www.free-api.ai/api/v1/responses

请求头

名称	必填	说明
Authorization	是	Bearer your-api-key
Content-Type	是	application/json

请求参数

字段	类型	必填	说明
model	string	是	模型 ID
input	string | array	否	输入内容，可以是字符串或消息数组
instructions	string	否	系统指令（等价于 system message）
max_output_tokens	integer	否	最大输出 Token 数
temperature	number	否	采样温度
top_p	number	否	核采样参数
stream	boolean	否	是否流式响应
tools	array	否	可调用的工具列表
tool_choice	string | object	否	工具选择策略
reasoning	object	否	推理配置，例如 { "effort": "medium", "summary": "auto" }
previous_response_id	string	否	上一轮响应 ID，用于延续对话
truncation	string	否	截断策略，auto 或 disabled

请求示例

cURL

curl https://www.free-api.ai/api/v1/responses \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "input": "帮我写一首关于秋天的短诗。",
    "instructions": "你是一个诗人，输出简洁而富有画面感的中文。",
    "reasoning": { "effort": "medium" }
  }'

多轮延续

curl https://www.free-api.ai/api/v1/responses \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "previous_response_id": "resp_xxxxxxxx",
    "input": "基于刚才的诗，再写一段散文。"
  }'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://www.free-api.ai/api/v1",
)

resp = client.responses.create(
    model="gpt-5",
    input="帮我写一首关于秋天的短诗。",
    instructions="你是一个诗人，输出简洁而富有画面感的中文。",
)
print(resp.output_text)

响应示例

非流式

{
  "id": "resp_xxxxxxxx",
  "object": "response",
  "created_at": 1730000000,
  "status": "completed",
  "model": "gpt-5",
  "output": [
    {
      "type": "message",
      "id": "msg_xxxxxxxx",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "落叶乘风入旧窗，一盏清茶半卷黄。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 32,
    "output_tokens": 18,
    "total_tokens": 50
  }
}

流式 (stream: true)

流式响应以 SSE 事件形式返回，每个事件包含 type 字段：

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"落叶"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"乘风"}

event: response.completed
data: {"type":"response.completed","response":{ ... }}

状态字段

status 可能取值：

值	含义
completed	响应已完成
in_progress	处理中（仅在非阻塞/轮询场景出现）
incomplete	响应被截断或中途终止
failed	执行失败

常见错误

HTTP 状态	说明
400	请求参数错误
401	鉴权失败
429	请求频率限制
5xx	上游服务异常