OpenAI Responses API#

通过 UniGateway 调用 OpenAI 的有状态 Responses API，用于面向 Agent 的工作流、内置工具和服务端会话状态管理。

概述#

Responses API 是 OpenAI 的下一代 Agent 交互接口，提供内置工具、结构化输出和服务端状态管理。

核心能力包括：

• 有状态会话：通过 previous_response_id 由服务端保留历史记录
• 内置工具：网页搜索、代码解释器、计算机使用、文件搜索
• 推理 token：模型在最终输出前进行推理
• 结构化输出：保证输出符合指定 JSON Schema

UniGateway 暴露以下端点：

• POST /v1/responses — 创建响应
• GET /v1/responses/{id} — 获取响应
• POST /v1/responses/{id}/input_items — 追加到会话

鉴权#

所有请求需要 UniGateway API Key：

Authorization: Bearer <YOUR_UNIGATEWAY_API_KEY>

支持的模型#

UniGateway 上支持 Responses API 的 OpenAI 模型：

查询实时模型列表：

curl https://api.unigateway.ai/v1/models \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

创建响应#

from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_UNIGATEWAY_API_KEY>",
    base_url="https://api.unigateway.ai/v1",
)

resp = client.responses.create(
    model="gpt-5.2",
    input="What is 15 * 27?",
    tools=[{"type": "code_interpreter"}],
)
print(resp.output_text)

基本请求#

curl https://api.unigateway.ai/v1/responses \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "用一段话解释量子计算。"
  }'

带会话历史#

curl https://api.unigateway.ai/v1/responses \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": [
      {"role": "user", "content": [{"type": "text", "text": "2+2 等于多少？"}]},
      {"role": "assistant", "content": [{"type": "text", "text": "4"}]},
      {"role": "user", "content": [{"type": "text", "text": "再乘以 10。"}]}
    ]
  }'

有状态会话#

curl https://api.unigateway.ai/v1/responses \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "再乘以 10。",
    "previous_response_id": "resp_abc123"
  }'

设置 previous_response_id 后，服务端自动管理会话历史。省略该字段时由客户端自行管理状态。

请求参数#

Input 数组格式#

每项包含：

{
  "role": "user",
  "content": [
    {"type": "text", "text": "..."},
    {"type": "image_url", "image_url": {"url": "..."}}
  ]
}

role 支持 user、assistant、system、developer。

响应格式#

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "text", "text": "量子计算利用叠加和纠缠..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 89,
    "total_tokens": 101
  }
}

响应字段#

输出项类型#

内置工具#

在 tools 数组中启用。

网页搜索#

{
  "tools": [
    {"type": "web_search_preview"}
  ]
}

代码解释器#

{
  "tools": [
    {"type": "code_interpreter"}
  ]
}

计算机使用#

{
  "tools": [
    {
      "type": "computer_use_preview",
      "environment": "browser"
    }
  ]
}

错误处理#