# List models

> GET /models 레퍼런스입니다. 게이트웨이가 반환하는 모델 객체, 목록에 담기지 않는 정보, 카탈로그가 비었을 때의 폴백, 에러, 예제를 설명합니다.

Source: https://kiln.bricksum.com/docs/ko/api-reference/models

`GET https://api.bricksum.com/v1/models`

게이트웨이가 현재 서빙할 수 있는 모델 ID를 OpenAI 모델 목록 형식으로 반환합니다. 목록은 모델 서버가 아니라 게이트웨이의 카탈로그에서 만듭니다. 각 항목에는 model 필드에 넣는 ID가 담기며, 단가, 컨텍스트 길이, 지원 기능은 이 응답에 포함되지 않습니다.

모델별 단가, 컨텍스트 길이, 지원 기능은 [모델](https://kiln.bricksum.com/docs/ko/models) 페이지에 있습니다.

## 인증

게이트웨이가 처리하는 엔드포인트의 인증 방식은 모두 같으며, [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에서 설명합니다.

## 요청

| 상태 | 설명 |
| --- | --- |
| 지원 | 게이트웨이가 처리하거나, 공개된 실측에서 동작이 확인된 항목입니다. |
| 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| 무시됨 | 200으로 수락되지만 적용되지 않습니다. 응답의 나머지는 정상입니다. |
| 미지원 | 에러로 거부되거나, 설명에 적힌 모델에서 동작하지 않습니다. |

| 필드 | 타입 | 필수 | 기본값 | 상태 | 설명 |
| --- | --- | --- | --- | --- | --- |
| `query string` | string |  |  | 무시됨 | 이 엔드포인트는 파라미터를 받지 않습니다. 쿼리 문자열은 수락되지만 응답에 영향을 주지 않습니다. 응답 본문에서 설명하는 폴백에서는 모델 서버로 전달되지 않습니다. |
| `request body` | none |  |  | 무시됨 | GET 요청에 본문을 보내도 읽지 않습니다. 본문 없이 요청하세요. |

결과를 바꾸는 것은 인증 헤더뿐이며, 모든 엔드포인트가 받는 것과 같은 헤더입니다. 그 밖에 보낼 것은 없습니다.

## 응답 본문

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `object` | string | "list" 고정값입니다. |
| `data[].id` | string | 모델 ID입니다(예: qwen3-32b). 추론 요청의 model 필드에 이 값을 넣습니다. |
| `data[].object` | string | "model" 고정값입니다. |
| `data[].created` | integer | Unix 초 단위 시각이며, 게이트웨이가 응답을 만드는 시점에 찍습니다. 한 응답의 모든 항목이 같은 값을 갖고, 호출할 때마다 값이 달라집니다. 모델이 추가된 시각을 나타내지 않습니다. |
| `data[].owned_by` | string | "bricksum" 고정값입니다. |

## 에러

이 엔드포인트의 에러는 OpenAI 형식({"error": {"message", "type", "param", "code"}})으로 반환됩니다. error.code 칸이 비어 있는 행은 요청이 엔드포인트에 도달하기 전에 게이트웨이가 반환하는 에러이며, 표 아래에 있는 본문 형식을 사용합니다.

| 상태 | error.code | 원인 | 조치 |
| --- | --- | --- | --- |
| 405 | `method_not_allowed` | 메서드가 GET이 아닙니다. | GET으로 요청하세요. 응답에는 Allow: GET 헤더가 실립니다. |
| 502 |  | 폴백에서만 발생합니다. 카탈로그가 비어 있고 모델 서버에 연결하지 못한 경우입니다. 본문은 JSON이 아니라 평문 upstream error입니다. | 잠시 기다린 뒤 재시도하세요. |
| 503 |  | 폴백에서만 발생합니다. 카탈로그가 비어 있고 선택할 모델 서버가 없는 경우입니다. 본문은 JSON이 아니라 평문 no upstream available입니다. | 잠시 기다린 뒤 재시도하고, 상태 페이지를 확인하세요. |

401, 402, 403, 429는 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환합니다. 이 에러들은 [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 한 번만 정리했습니다.

인증, 크레딧, 예산, 레이트 리밋(분당 요청 수, 분당 토큰 수) 에러는 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환합니다. 본문에는 error.code 대신 error.type이 담깁니다.

```json
{
  "error": {
    "message": "invalid API key",
    "type": "authorization"
  }
}
```

전체 상태 코드는 [에러](https://kiln.bricksum.com/docs/ko/errors) 페이지에 있습니다.

## 제한

- 과금: 과금되지 않습니다. 게이트웨이는 이 엔드포인트에 대해 usage 이벤트를 발행하지 않으며, 응답에 X-Neocloud-Generation-Id 헤더가 없습니다.
- 목록 내용: 게이트웨이가 서빙하는 모델만 담깁니다. 폐기 예정 모델과 준비 중인 모델은 빠지므로, 여기에 없는 ID는 추론 엔드포인트에서 404(model_not_found)로 거부됩니다.
- 빈 카탈로그: 게이트웨이가 서빙 가능한 모델을 하나도 알 수 없으면 요청을 모델 서버로 프록시하고 그 서버의 응답을 그대로 반환합니다. 이때 본문의 ID는 모델 서버의 것이므로, 게이트웨이가 서빙하는 ID와 다를 수 있습니다.
- 단건 조회는 제공하지 않습니다: GET /models/{model}은 서빙되지 않습니다. 게이트웨이가 그 경로를 핸들러가 없는 서비스로 보내므로 에러 객체가 아니라 평문 404가 돌아옵니다. 개별 모델은 위 목록에서 읽으세요.

429의 헤더와 재시도 방법은 [레이트 리밋](https://kiln.bricksum.com/docs/ko/rate-limits) 페이지에 있습니다.

## 예제

### 요청

**cURL**
```bash
curl https://api.bricksum.com/v1/models \
  -H "Authorization: Bearer $KILN_API_KEY"
```

**Python**
```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bricksum.com/v1",
    api_key=os.environ["KILN_API_KEY"],
)

for model in client.models.list():
    print(model.id)
```

**JavaScript**
```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bricksum.com/v1",
  apiKey: process.env.KILN_API_KEY,
});

const list = await client.models.list();
for (const model of list.data) console.log(model.id);
```

### 응답

**200 OK**
```json
{
  "object": "list",
  "data": [
    {
      "id": "qwen3-32b",
      "object": "model",
      "created": 1710000000,
      "owned_by": "bricksum"
    }
  ]
}
```

**405 Method Not Allowed**
```json
{
  "error": {
    "message": "Method POST is not allowed on /v1/models (use GET).",
    "type": "invalid_request_error",
    "param": "",
    "code": "method_not_allowed"
  }
}
```