# 创建聊天补全

**API:** Model API

**Endpoint:** `POST /api/v1/chat/completions`

兼容 OpenAI 的 Chat Completions API。设置 stream=true 可接收 Server-Sent Events。响应和错误封装遵循 Chat Completions/OpenAI 兼容结构。

## 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: `ChatCompletionRequest` (`#/components/schemas/ChatCompletionRequest`)

```json
{
  "type": "object",
  "required": [
    "model",
    "messages"
  ],
  "properties": {
    "model": {
      "type": "string"
    },
    "messages": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/components/schemas/ChatMessage"
      }
    },
    "stream": {
      "type": "boolean",
      "default": false
    },
    "temperature": {
      "type": "number",
      "minimum": 0
    },
    "top_p": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "n": {
      "type": "integer",
      "minimum": 1
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1
    },
    "max_completion_tokens": {
      "type": "integer",
      "minimum": 1
    },
    "stop": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "tool_choice": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "response_format": {
      "type": "object",
      "additionalProperties": true
    },
    "user": {
      "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",
  "messages": [
    {
      "role": "user",
      "content": "Write a one-sentence greeting."
    }
  ],
  "stream": false
}
```

## Responses

### 200 — 聊天补全或流式响应

**application/json**

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

**text/event-stream**

Schema: string

```json
{
  "type": "string",
  "description": "包含 chat.completion.chunk 数据事件的 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

### ChatChoice

`#/components/schemas/ChatChoice`

```json
{
  "type": "object",
  "properties": {
    "index": {
      "type": "integer"
    },
    "message": {
      "$ref": "#/components/schemas/ChatMessage"
    },
    "finish_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "logprobs": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}
```

### ChatCompletionResponse

`#/components/schemas/ChatCompletionResponse`

```json
{
  "type": "object",
  "required": [
    "id",
    "object",
    "choices"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "type": "string",
      "description": "非流式响应通常为 chat.completion。"
    },
    "created": {
      "type": "integer",
      "format": "int64"
    },
    "model": {
      "type": "string"
    },
    "choices": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ChatChoice"
      }
    },
    "usage": {
      "$ref": "#/components/schemas/Usage"
    },
    "system_fingerprint": {
      "type": "string"
    }
  },
  "additionalProperties": true
}
```

### ChatMessage

`#/components/schemas/ChatMessage`

```json
{
  "type": "object",
  "required": [
    "role",
    "content"
  ],
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "system",
        "developer",
        "user",
        "assistant",
        "tool"
      ]
    },
    "content": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "type": "string"
    },
    "tool_call_id": {
      "type": "string"
    },
    "tool_calls": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}
```

### 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
}
```

### Usage

`#/components/schemas/Usage`

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