---
title: "创建 Response"
description: "创建 Response（OpenAI Responses 协议）。"
canonical: "https://pirouter.ai/zh/docs/api/responses"
last-updated: "2026-10-13"
lang: "zh"
---

# 创建 Response

创建 Response（OpenAI Responses 协议）。

`POST https://api.pirouter.ai/v1/responses`

兼容 OpenAI 的 Responses API。一个模型只能用它登记接受的协议调用；用它不接受的协议调用，返回 `validation_failed`（422）。请求带 `"stream": true` 时，响应是由带类型的响应事件组成的 Server-Sent Events 流；否则是单个 JSON 响应体。平台只读取请求 schema 里列出的字段；其他字段全部原样转发给上游 provider。

## 鉴权

用下面任一请求头传 API key。

| 请求头 | 值 | 说明 |
| --- | --- | --- |
| `Authorization` | `Bearer sk-pi-…` | 平台签发的 API key，以 `sk-pi-` 开头，作为 Bearer token 发送。 |
| `X-Api-Key` | `sk-pi-…` | 同一个平台签发的 `sk-pi-` key，放在 `X-Api-Key` 请求头里发送。只有 `Authorization` 缺失或为空时才读取这个请求头；两个都带时，以 `Authorization` 为准。两个请求头都接受不带 `Bearer ` 前缀的裸 key。 |

## 请求体

`application/json`

OpenAI Responses 请求。这里只列出平台会读取的字段；协议的其余字段原样转发给上游。路由字段 `provider` 和 `models` 由路由使用，转发前会被移除。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，格式为 "vendor/model"。 |
| `input` | string \| object[] | 否 | 给模型的输入，可以是字符串，也可以是协议定义的输入项数组。原样转发。 |
| `stream` | boolean | 否 | 为 true 时，以 Server-Sent Events 流的形式响应。 默认值: `false`. |
| `models` | string[] · max 3 | 否 | 回退模型列表。当前模型的所有部署都在返回首字节之前失败时，在 `model` 之后按数组顺序依次尝试这些模型（见「运行时回退」）。与 `model` 或前面条目重复的条目会被丢弃；未提供 `model` 时，第一个条目作为主模型。每个条目都必须存在（否则返回 404 model_not_found，并指出该条目）；超过 3 个时返回 validation_failed。不转发给上游。 |
| `provider` | object | 否 | 按请求设置的 provider 路由偏好，在所请求的模型有多个 provider 提供时生效。限制类字段（`only`、`ignore`、`data_collection`、`zdr`、`quantizations`）只能在工作区路由设置的基础上收紧。工作区的排序方式（`order` 和 `sort`）只是默认值，请求里给出时会整体替换它。provider 名称使用平台 ID，匹配时不区分大小写，另外接受别名 `google-vertex`（gcp）、`google-ai-studio`（gemini）和 `amazon-bedrock`（aws）。已知但尚未实现的字段会被拒绝，提示 `provider.<field> is not supported yet`；其他未知的键也会被拒绝，提示 `provider: unrecognized key "<key>"`。 |
| `provider.order` | string[] | 否 | 优先尝试的 provider，按此顺序；未列出的 provider 排在它们之后。 |
| `provider.only` | string[] | 否 | 只使用这些 provider（与工作区的允许列表取交集）。 |
| `provider.ignore` | string[] | 否 | 不使用这些 provider（追加到工作区的忽略列表）。优先级高于 `only`。 |
| `provider.allow_fallbacks` | boolean | 否 | 设为 `false` 且同时给出 `order` 时，只有 `order` 里的 provider 可以处理请求。工作区设为 `false` 时，请求无法放宽。 默认值: `true`. |
| `provider.sort` | string \| object | 否 | 在每个 `order` 层级内，按 `input_text + output_text` 的单价从低到高给 provider 排序。不设时，由部署权重决定。 |
| `provider.sort.by` | string | 是 | 可选值: `price`. |
| `provider.data_collection` | string | 否 | `deny` 会排除可能用提示词训练模型、或保留提示词超过有限期限的 provider（未声明的按「可能」处理）。 可选值: `allow`, `deny`. 默认值: `"allow"`. |
| `provider.zdr` | boolean | 否 | 只使用零数据保留的 provider。 默认值: `false`. |
| `provider.quantizations` | string[] | 否 | 只使用精度在此列表内的部署。 可选值: `fp4`, `int4`, `int8`, `fp8`, `fp16`, `bf16`, `fp32`, `unknown`. |

## 响应

`200` `application/json`, `text/event-stream`

响应对象，结构由 OpenAI Responses 协议定义；响应体来自上游，原样透传。流式请求得到 SSE 流，由该协议的带类型事件组成（`event:` 加 `data:` 行）。

## 错误

| 状态码 | 错误码 | 说明 |
| --- | --- | --- |
| `400` | `invalid_request` | 请求缺少必填字段（`invalid_request`）：请求体既没有 `model` 也没有 `models` 时，返回 `model is required`。 |
| `401` | `invalid_api_key`, `api_key_not_found`, `api_key_revoked`, `api_key_expired` | API key 缺失或格式错误（`invalid_api_key`）、不存在（`api_key_not_found`）、已吊销（`api_key_revoked`）或已过期（`api_key_expired`）。 |
| `402` | `insufficient_balance` | 钱包余额不足以支付这次调用（`insufficient_balance`）。 |
| `404` | `model_not_found`, `no_eligible_provider` | 所请求的模型 ID 不存在或未启用（`model_not_found`）；或者请求的 `provider` 偏好与工作区路由设置合并后，没有 provider 能提供该模型（`no_eligible_provider`，`error.metadata` 里带有路由筛选漏斗）。 |
| `422` | `validation_failed` | 请求未通过校验（`validation_failed`）：该模型不在本端点提供（错误信息会列出它提供的端点），或者某个路由字段（`provider`、`models`、`route`、`preset`）不符合规则。错误信息会指出原因。 |
| `429` | `rate_limited` | 请求因限流被拒绝（`rate_limited`）。 |
| `500` | `internal_error` | 其他失败：没有健康的上游可以处理请求时返回 `provider_unavailable`（503）；平台侧出现意外故障时返回 `internal_error`（500）。 |
| `503` | `provider_unavailable` | 其他失败：没有健康的上游可以处理请求时返回 `provider_unavailable`（503）；平台侧出现意外故障时返回 `internal_error`（500）。 |

错误体

```json
{
  "error": {
    "message": "No such model. Model names are vendor-qualified (vendor/model), so a name copied from a provider's own docs needs its vendor prefix added. Call GET /v1/models for the slugs this gateway serves.",
    "type": "not_found_error",
    "code": "model_not_found"
  }
}
```

## 响应头

每个响应头后面列出它会出现在哪些状态码的响应里。

| 响应头 | 出现于 | 说明 |
| --- | --- | --- |
| `X-Pi-Trace-Id` | `200`, `400`, `401`, `402`, `404`, `422`, `429`, `default` | 平台请求 id，由网关生成。推理端点的每个响应都带；反馈问题时请附上它。 |
| `Access-Control-Allow-Origin` | `200`, `400`, `401`, `402`, `404`, `422`, `429`, `default` | 恒为 `*`。凭证是携带 API key 的请求头，从不是 cookie。 |
| `Access-Control-Expose-Headers` | `200`, `400`, `401`, `402`, `404`, `422`, `429`, `default` | 列出每一个 `X-Pi-*` 响应头，外加 `Retry-After` 与 `Content-Encoding`，让浏览器里的代码能读到它们。 |
| `X-Pi-Provider` | `200`, `default` | 处理这次响应的 provider，取值与 `provider.order`、`GET /v1/models/{vendor}/{model}/endpoints` 同一套词表。只有上游 provider 作出应答时才有（一次补全或一次上游错误）；发生 fallback 后是接手的那个 provider。 |
| `X-Pi-Model` | `200`, `default` | 处理这次响应的模型 slug，与响应体里的 `model` 是同一个值。由 fallback 模型接手时就是那个模型。只有上游 provider 作出应答时才有。 |
| `X-Pi-Upstream-Model` | `200`, `default` | 上游 provider 在它自己的响应里报告的完整模型 id，原样透传（流式时取自第一个数据事件）。上游响应没有给出模型时不带这个头；不会用平台自己的记录补上。 |
| `X-Pi-Upstream-Request-Id` | `200`, `default` | 上游 provider 自己的请求 id，原样透传，用于在 provider 一侧查这次调用。provider 没有返回时不带这个头。 |

## 请求示例

cURL

```bash
curl https://api.pirouter.ai/v1/responses \
  -H "Authorization: Bearer $PIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-sol",
    "input": "Hello!"
  }'
```

Python

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.pirouter.ai/v1",
    api_key=os.environ["PIROUTER_API_KEY"],
)

response = client.responses.create(
    model="openai/gpt-6-sol",
    input="Hello!",
)
print(response.output_text)
```

TypeScript

```ts
import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.pirouter.ai/v1',
  apiKey: process.env.PIROUTER_API_KEY,
})

const response = await client.responses.create({
  model: 'openai/gpt-6-sol',
  input: 'Hello!',
})
console.log(response.output_text)
```

## 响应示例

`200` `application/json`

```json
{
  "id": "resp_0064aae7eb7c...",
  "object": "response",
  "created_at": 1791795973,
  "status": "completed",
  "model": "openai/gpt-6-sol",
  "output": [
    {
      "id": "msg_0064aae7eb7c...",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help?",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 8,
    "output_tokens": 11,
    "total_tokens": 19
  }
}
```

`200` `text/event-stream`

```text
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_0c7f2fbaa808...","object":"response","created_at":1791795975,"status":"in_progress","model":"openai/gpt-6-sol","output":[]}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,"response":{"id":"resp_0c7f2fbaa808...","object":"response","created_at":1791795975,"status":"in_progress","model":"openai/gpt-6-sol","output":[]}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"id":"msg_0c7f2fbaa808...","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":3,"output_index":0,"content_index":0,"item_id":"msg_0c7f2fbaa808...","part":{"type":"output_text","text":"","annotations":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"output_index":0,"content_index":0,"item_id":"msg_0c7f2fbaa808...","delta":"Hi"}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":6,"output_index":0,"content_index":0,"item_id":"msg_0c7f2fbaa808...","text":"Hi!"}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":7,"output_index":0,"content_index":0,"item_id":"msg_0c7f2fbaa808...","part":{"type":"output_text","text":"Hi!","annotations":[]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":8,"output_index":0,"item":{"id":"msg_0c7f2fbaa808...","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi!","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":9,"response":{"id":"resp_0c7f2fbaa808...","object":"response","created_at":1791795975,"status":"completed","model":"openai/gpt-6-sol","output":[{"id":"msg_0c7f2fbaa808...","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi!","annotations":[]}]}],"usage":{"input_tokens":8,"output_tokens":6,"total_tokens":14}}}
```