# 채팅 완료 생성

**API:** Model API

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

OpenAI 호환 Chat Completions API입니다. stream=true로 설정하면 서버 전송 이벤트(SSE)를 받습니다. 응답 및 오류 봉투는 Chat Completions/OpenAI 호환 형식을 따릅니다.

## Base URL

- `https://openapi.felo.ai` — 프로덕션

## Authentication

- `FeloBearerAuth` (http bearer) — Felo API 키를 `Authorization: Bearer <key>` 형식으로 전송합니다.
- `FeloApiKey` (apiKey in header `X-API-Key`) — Felo API 키를 `X-API-Key: <key>` 형식으로 전송합니다.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Felo-Channel` | header | no | string, default: "default" | 공개 채널 코드를 쉼표로 구분한 순서 있는 목록입니다. 이 헤더를 생략하면 default를 사용하며, default는 단독으로만 사용해야 합니다. 지갑 모드에서 default는 모델의 유효 공개 채널 순서를 역순으로 스캔하고, 게시되지 않았거나 사용할 수 없는 채널을 건너뛰며, 사용 가능한 첫 번째 채널의 공급자를 선택합니다. 동일한 업스트림 모델 ID와 서비스 티어를 가진 해당 공급자의 사용 가능한 엔드포인트도 포함합니다. 명시적 채널은 클라이언트가 지정한 순서로 검증되며, 첫 번째 채널의 공급자 그룹만 제출됩니다. 다른 공급자로의 자동 fallback은 없습니다. 레거시 공급자 헤더로는 채널 라우팅을 재정의할 수 없습니다. |

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