# 创建模型响应

**API:** Model API

**Endpoint:** `POST /api/v1/responses`

兼容 OpenAI Responses API 的端点。成功的非流式响应使用 Responses 对象结构；当 stream=true 时，该端点返回 Responses SSE 事件。即使 HTTP 请求本身已完成，失败的 Responses 对象也可能带有 status=failed 和 error={code,message}。

## Base URL

- `https://openapi.felo.ai` — 生产环境

## Authentication

- `FeloBearerAuth` (http bearer) — 以 `Authorization: Bearer <key>` 形式发送的 Felo API 密钥。
- `FeloApiKey` (apiKey in header `X-API-Key`) — 以 `X-API-Key: <key>` 形式发送的 Felo API 密钥。

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Felo-Channel` | header | no | string, default: "default" | 以逗号分隔、按顺序排列的公开通道代码。省略此请求头表示使用 default；default 必须单独使用。在钱包模式下，default 会从后往前扫描该模型实际生效的公开通道顺序，跳过未发布或不可用的通道，并选择第一个可用通道的提供方。它会纳入该提供方下上游模型 ID 和服务层级相同的可用端点。显式通道按客户端指定的顺序校验；仅提交第一个通道所属的提供方组。不会自动回退到其他提供方。旧版提供方请求头无法覆盖通道路由。 |

## Request body

Required: **yes**

### application/json

Schema: `ResponsesRequest` (`#/components/schemas/ResponsesRequest`)

```json
{
  "type": "object",
  "required": [
    "model",
    "input"
  ],
  "properties": {
    "model": {
      "type": "string"
    },
    "input": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ],
      "description": "Reference a Felo PDF with input_file.file_id or an uploaded image with input_image.file_id in a message content array. The model must be enabled for the attachment type. The combined limit for Felo file references is 50 MB per request. PDF file_url/file_data and image_url (HTTPS or a data URL) use the native format."
    },
    "instructions": {
      "type": "string"
    },
    "stream": {
      "type": "boolean",
      "default": false
    },
    "temperature": {
      "type": "number",
      "minimum": 0
    },
    "top_p": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "max_output_tokens": {
      "type": "integer",
      "minimum": 1
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "tool_choice": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "previous_response_id": {
      "type": "string"
    },
    "store": {
      "type": "boolean"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    },
    "text": {
      "type": "object",
      "additionalProperties": true
    },
    "reasoning": {
      "type": "object",
      "additionalProperties": true
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "service_tier": {
      "type": [
        "string",
        "null"
      ],
      "default": "default",
      "description": "目前仅支持 default（standard）。省略、null、别名以及不支持的字符串都会回退到 default；其他类型返回 HTTP 400。已配置的通道和价格保持不变。文本 API 发送提供方的标准值；Decisions 和生成类 API 省略该上游字段。"
    }
  },
  "additionalProperties": true
}
```

Example:

```json
{
  "model": "gpt-5.5",
  "input": "Explain why the sky is blue in one sentence.",
  "stream": false
}
```

## Responses

### 200 — 响应对象或流式响应事件

**application/json**

Schema: `ResponsesResponse` (`#/components/schemas/ResponsesResponse`)

**text/event-stream**

Schema: string

```json
{
  "type": "string",
  "description": "Responses API 的 SSE 事件。"
}
```

### 400 — 请求、模型或提供方映射无效

**application/json**

Schema: `OpenAIErrorResponse` (`#/components/schemas/OpenAIErrorResponse`)

### 401 — Felo API 密钥无效或缺失

**application/json**

Schema: `OpenAIErrorResponse` (`#/components/schemas/OpenAIErrorResponse`)

### 402 — 余额不足

**application/json**

Schema: `OpenAIErrorResponse` (`#/components/schemas/OpenAIErrorResponse`)

### 403 — 该账户未获授权使用此模型。已停用的模型也会在调用上游之前被拒绝。已接受的请求和任务继续进行。

**application/json**

Schema: `OpenAIErrorResponse` (`#/components/schemas/OpenAIErrorResponse`)

### 429 — 已达到消费或请求上限

**application/json**

Schema: `OpenAIErrorResponse` (`#/components/schemas/OpenAIErrorResponse`)

### 502 — 上游提供方请求失败

**application/json**

Schema: `OpenAIErrorResponse` (`#/components/schemas/OpenAIErrorResponse`)

### 503 — 提供方或计费服务不可用

**application/json**

Schema: `OpenAIErrorResponse` (`#/components/schemas/OpenAIErrorResponse`)

## Schema definitions

### OpenAIErrorResponse

`#/components/schemas/OpenAIErrorResponse`

```json
{
  "type": "object",
  "description": "兼容 OpenAI 的错误封装。Router 可能只包含 code 和 message，而不包含所有可选的上游字段。",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "message"
      ],
      "properties": {
        "message": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "description": "提供时为 OpenAI 兼容的错误类型。"
        },
        "param": {
          "type": [
            "string",
            "null"
          ]
        },
        "code": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}
```

### ResponsesError

`#/components/schemas/ResponsesError`

```json
{
  "type": "object",
  "required": [
    "code",
    "message"
  ],
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true
}
```

### ResponsesResponse

`#/components/schemas/ResponsesResponse`

```json
{
  "type": "object",
  "required": [
    "id",
    "object",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "type": "string",
      "const": "response"
    },
    "status": {
      "type": "string",
      "enum": [
        "completed",
        "failed",
        "in_progress",
        "cancelled",
        "queued",
        "incomplete"
      ]
    },
    "output": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "output_text": {
      "type": "string"
    },
    "error": {
      "$ref": "#/components/schemas/ResponsesError"
    },
    "usage": {
      "$ref": "#/components/schemas/Usage"
    },
    "model": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}
```

### Usage

`#/components/schemas/Usage`

```json
{
  "type": "object",
  "description": "提供方用量对象。字段因端点和提供方而异。",
  "additionalProperties": true
}
```
