# 建立聊天補全

**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（標準）。省略、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
}
```
