# OpenAI 多模态响应接口
> 使用 OpenAI Responses 结构，是 Chat Completions 之外的另一种形态
> 内置工具（网页搜索、文件检索、代码执行）由服务端直接编排
> 支持跨轮次保留上下文，不必自己重发历史
`POST /v1/responses`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 必填) — 模型 ID。
- `input` (string / array) — 输入内容。可以是纯字符串，也可以是消息数组。
- `input[].role` (string / 可选) — 消息角色，取值 `user`、`assistant`、`system`、`developer`。
- `input[].content` (string / array) — 消息正文。传数组时元素含 `type`，可混排文本与图片。
- `instructions` (string / 可选) — 系统级指令。相当于把 system 提示提到顶层，优先级高于 input 里的内容。
- `max_output_tokens` (integer / 可选) — 输出 token 上限。注意这里带 `output`，与 Chat Completions 的 `max_tokens` 不同。
- `temperature` (number / 可选) — 采样温度。
- `top_p` (number / 可选) — 核采样阈值。
- `tools` (array / 可选) — 内置工具清单。支持 `web_search_preview`、`file_search`、`code_interpreter` 等类型。
- `tools[].type` (string / 必填) — 工具类型标识。
- `tool_choice` (string / 可选) — 工具选择策略，取值 `auto`、`required` 或 `none`。
- `previous_response_id` (string / 可选) — 上一轮响应的 ID。传入后服务端会自动带上历史上下文，不必重发 messages。
- `store` (boolean / 可选) — 是否在服务端保留这次响应，供后续用 `previous_response_id` 引用。
- `stream` (boolean / 可选) — 是否流式返回。流式下事件类型与 Chat Completions 不同，按事件名区分。
- `text.format.type` (string / 可选) — 结构化输出格式，`json_schema` 时需同时给 `schema`。
- `reasoning.effort` (string / 可选) — 推理强度，取值 `low`、`medium`、`high`。仅推理模型支持。
## 响应
- `id` (string) — 响应 ID，形如 `resp_`。可作为下一轮的 `previous_response_id`。
- `object` (string) — 固定为 `response`。
- `status` (string) — 状态。`completed` 正常结束，`incomplete` 未完成，`failed` 失败。
- `output` (array) — 输出项数组。元素类型可能是 `message`、`web_search_call`、`reasoning` 等。
- `output[].type` (string) — 输出项类型。
- `output[].content` (array) — `type` 为 `message` 时的内容数组，元素含 `type: output_text` 与 `text`。
- `usage.input_tokens` (integer) — 输入 token 数。
- `usage.output_tokens` (integer) — 输出 token 数。
- `usage.total_tokens` (integer) — 两者之和。
## 与 Chat Completions 的差异
| Chat Completions | Responses |
|---|---|
| `messages` | `input` |
| `max_tokens` | `max_output_tokens` |
| 无状态，每轮重发历史 | `previous_response_id` 承接上下文 |
| 工具调用返回 `tool_calls` | 工具结果直接内联在 `output` 里 |
| `choices[].message.content` | `output[].content[].text` |
> **Note:** 
> 两者返回结构差别较大。如果现有代码是按 `choices[0].message.content` 解析的，切到 Responses 需要改解析逻辑。
## 支持的模型列表
以下模型均可通过本接口调用，清单由模型目录自动生成，实际可用范围以你的账号分组为准：
:::models
> **Note:** 想按上下文长度、价格或能力标签挑选模型，可查阅 [模型列表元数据接口](../models.html)，或直接读取 `GET /api/pricing`。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 使用示例
### 基础对话
输入放在 `input` 字段，可以是纯文本字符串，也可以是消息数组。返回的正文在 `output[].content[].text` 里。
### 系统提示词
用 `instructions` 字段设定角色与约束，位置在顶层，和 `input` 平级。
### 多轮对话
两种方式承接上下文：传 `previous_response_id` 让服务端接上文的 id，或者把完整历史数组放进 `input`。前者省 token，后者更可控。
### 结构化输出
`text.format` 指定返回 JSON，配合 `schema` 约束字段。适合需要严格字段名的解析场景。
### 内置工具
可以挂载 `web_search` 这类服务端工具，模型会自行调用并把结果并进回答，不需要自己写函数。
**基础对话{Basic chat}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/responses' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-mini",
    "input": "用一句话说明什么是反向代理"
  }'
```
**基础对话{Basic chat}::Python**
```
import requests
url = "https://api.oairoute.com/v1/responses"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "gpt-4o-mini",
    "input": "用一句话说明什么是反向代理"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**基础对话{Basic chat}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "gpt-4o-mini",
    "input": "用一句话说明什么是反向代理"
  }),
});
console.log(await res.json());
```
**系统提示词{System prompt}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/responses' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-mini",
    "instructions": "你是代码审查助手，只指出问题，不重写代码。",
    "input": "审查这段函数：def f(x): return x/0"
  }'
```
**系统提示词{System prompt}::Python**
```
import requests
url = "https://api.oairoute.com/v1/responses"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "gpt-4o-mini",
    "instructions": "你是代码审查助手，只指出问题，不重写代码。",
    "input": "审查这段函数：def f(x): return x/0"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**系统提示词{System prompt}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "gpt-4o-mini",
    "instructions": "你是代码审查助手，只指出问题，不重写代码。",
    "input": "审查这段函数：def f(x): return x/0"
  }),
});
console.log(await res.json());
```
**多轮对话{Multi-turn chat}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/responses' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-mini",
    "previous_response_id": "resp_67c9fdcecf488190bdd9a0409de3c",
    "input": "那它的成本大概是多少"
  }'
```
**多轮对话{Multi-turn chat}::Python**
```
import requests
url = "https://api.oairoute.com/v1/responses"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "gpt-4o-mini",
    "previous_response_id": "resp_67c9fdcecf488190bdd9a0409de3c",
    "input": "那它的成本大概是多少"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多轮对话{Multi-turn chat}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "gpt-4o-mini",
    "previous_response_id": "resp_67c9fdcecf488190bdd9a0409de3c",
    "input": "那它的成本大概是多少"
  }),
});
console.log(await res.json());
```
**结构化输出{Structured output}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/responses' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-mini",
    "input": "我叫李明，住在杭州。",
    "text": {
      "format": {
        "type": "json_schema",
        "name": "profile",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "city": { "type": "string" }
          },
          "required": ["name", "city"]
        }
      }
    }
  }'
```
**结构化输出{Structured output}::Python**
```
import requests
url = "https://api.oairoute.com/v1/responses"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "gpt-4o-mini",
    "input": "我叫李明，住在杭州。",
    "text": {
      "format": {
        "type": "json_schema",
        "name": "profile",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "city": { "type": "string" }
          },
          "required": ["name", "city"]
        }
      }
    }
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**结构化输出{Structured output}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "gpt-4o-mini",
    "input": "我叫李明，住在杭州。",
    "text": {
      "format": {
        "type": "json_schema",
        "name": "profile",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "city": { "type": "string" }
          },
          "required": ["name", "city"]
        }
      }
    }
  }),
});
console.log(await res.json());
```
**内置工具{Built-in tools}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/responses' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-mini",
    "tools": [{ "type": "web_search" }],
    "input": "查一下 oairoute 的官网地址"
  }'
```
**内置工具{Built-in tools}::Python**
```
import requests
url = "https://api.oairoute.com/v1/responses"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "gpt-4o-mini",
    "tools": [{ "type": "web_search" }],
    "input": "查一下 oairoute 的官网地址"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**内置工具{Built-in tools}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "gpt-4o-mini",
    "tools": [{ "type": "web_search" }],
    "input": "查一下 oairoute 的官网地址"
  }),
});
console.log(await res.json());
```
**200 基础对话{Basic chat}**
```
{
  "id": "resp_01KA",
  "object": "response",
  "created_at": 1763088289,
  "status": "completed",
  "model": "gpt-4o-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_01KA",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "反向代理是位于服务器前面、替服务器接收客户端请求并转发的中间层。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 16,
    "output_tokens": 28,
    "total_tokens": 44
  }
}
```
**200 系统提示词{System prompt}**
```
{
  "id": "resp_01KB",
  "object": "response",
  "created_at": 1763088306,
  "status": "completed",
  "model": "gpt-4o-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_01KB",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "第 1 行除以零，调用时必然抛出 ZeroDivisionError。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 38,
    "output_tokens": 21,
    "total_tokens": 59
  }
}
```
**200 多轮对话{Multi-turn chat}**
```
{
  "id": "resp_01KC",
  "object": "response",
  "created_at": 1763088323,
  "status": "completed",
  "model": "gpt-4o-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_01KC",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "按带宽和请求数计费，小规模使用每月通常只需几十元。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 64,
    "output_tokens": 24,
    "total_tokens": 88
  }
}
```
**200 结构化输出{Structured output}**
```
{
  "id": "resp_01KD",
  "object": "response",
  "created_at": 1763088340,
  "status": "completed",
  "model": "gpt-4o-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_01KD",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "{\"name\": \"李明\", \"city\": \"杭州\"}"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 52,
    "output_tokens": 12,
    "total_tokens": 64
  }
}
```
**200 内置工具{Built-in tools}**
```
{
  "id": "resp_01KE",
  "object": "response",
  "created_at": 1763088357,
  "status": "completed",
  "model": "gpt-4o-mini",
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_01KE",
      "status": "completed"
    },
    {
      "type": "message",
      "id": "msg_01KE",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "OAIRoute 的官网地址是 https://api.oairoute.com。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 310,
    "output_tokens": 22,
    "total_tokens": 332
  }
}
```