> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 모델 목록

> API 키로 사용 가능한 모델 목록을 OpenAI, Anthropic 또는 Gemini 형식으로 조회합니다.

## 소개

API 키로 사용 가능한 모든 모델을 조회합니다. **동일한 엔드포인트** `https://api.gravitex.ai/v1/models`는 요청 헤더에 따라 해당 플랫폼의 네이티브 형식으로 응답을 자동 반환하므로, URL을 바꾸거나 여러 통합을 유지할 필요가 없습니다.

<Card title="자동 형식 감지" icon="wand-magic-sparkles">
  GravitexAI는 인증 헤더를 검사하여 클라이언트 유형을 감지하고, **공식 OpenAI / Anthropic / Gemini ListModels 스키마**로 응답을 반환하므로 네이티브 SDK를 바로 사용할 수 있습니다.
</Card>

## 형식 감지 규칙

| 요청 시그니처                                   | 응답 형식         |
| ----------------------------------------- | ------------- |
| `x-api-key` + `anthropic-version` 헤더      | **Anthropic** |
| `x-goog-api-key` 헤더 또는 `?key=xxx` 쿼리 매개변수 | **Gemini**    |
| `Authorization: Bearer ...` (기본값)         | **OpenAI**    |

<Note>
  여러 자격 증명이 함께 전달되면 **우선순위**는 Anthropic > Gemini > OpenAI입니다.
</Note>

## 인증

<ParamField header="Authorization" type="string">
  OpenAI 호환 인증, 형식: `Bearer sk-xxxxxxxxxx`
</ParamField>

<ParamField header="x-api-key" type="string">
  Anthropic 인증 — 원시 API 키(`Bearer` 접두사 없음)
</ParamField>

<ParamField header="anthropic-version" type="string">
  Anthropic API 버전, 예: `2023-06-01`
</ParamField>

<ParamField header="x-goog-api-key" type="string">
  Gemini 인증 — 원시 API 키
</ParamField>

## 요청 예시

<Tabs>
  <Tab title="OpenAI format">
    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.gravitex.ai/v1/models \
        -H "Authorization: Bearer sk-XyLy**************************mIqSt"
      ```

      ```python Python theme={null}
      from openai import OpenAI

      client = OpenAI(
          api_key="sk-XyLy**************************mIqSt",
          base_url="https://api.gravitex.ai/v1"
      )

      models = client.models.list()

      for model in models.data:
          print(f"{model.id}  ({model.owned_by})")
      ```

      ```javascript Node.js theme={null}
      import OpenAI from 'openai';

      const client = new OpenAI({
        apiKey: 'sk-XyLy**************************mIqSt',
        baseURL: 'https://api.gravitex.ai/v1'
      });

      const models = await client.models.list();
      models.data.forEach(m => console.log(`${m.id}  (${m.owned_by})`));
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Anthropic format">
    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.gravitex.ai/v1/models \
        -H "x-api-key: sk-XyLy**************************mIqSt" \
        -H "anthropic-version: 2023-06-01"
      ```

      ```python Python theme={null}
      import anthropic

      client = anthropic.Anthropic(
          api_key="sk-XyLy**************************mIqSt",
          base_url="https://api.gravitex.ai"
      )

      for model in client.models.list().data:
          print(f"{model.id}  ({model.display_name})")
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Gemini format">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.gravitex.ai/v1/models" \
        -H "x-goog-api-key: sk-XyLy**************************mIqSt"
      ```

      ```python Python theme={null}
      import requests

      resp = requests.get(
          "https://api.gravitex.ai/v1/models",
          headers={"x-goog-api-key": "sk-XyLy**************************mIqSt"}
      )

      for model in resp.json()["models"]:
          print(f"{model['name']}  ({model['displayName']})")
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 응답 예시

<Tabs>
  <Tab title="OpenAI format">
    ```json theme={null}
    {
      "object": "list",
      "data": [
        {
          "id": "gpt-5.4",
          "object": "model",
          "created": 1715232000,
          "owned_by": "openai"
        },
        {
          "id": "claude-sonnet-4-5-20250929",
          "object": "model",
          "created": 1743465600,
          "owned_by": "anthropic"
        },
        {
          "id": "gemini-2.5-pro",
          "object": "model",
          "created": 1746057600,
          "owned_by": "google"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Anthropic format">
    ```json theme={null}
    {
      "data": [
        {
          "type": "model",
          "id": "claude-opus-4-5-20251101",
          "display_name": "Claude Opus 4.5",
          "created_at": "2025-11-01T00:00:00Z"
        },
        {
          "type": "model",
          "id": "claude-sonnet-4-5-20250929",
          "display_name": "Claude Sonnet 4.5",
          "created_at": "2025-09-29T00:00:00Z"
        }
      ],
      "has_more": false,
      "first_id": "claude-opus-4-5-20251101",
      "last_id": "claude-sonnet-4-5-20250929"
    }
    ```
  </Tab>

  <Tab title="Gemini format">
    ```json theme={null}
    {
      "models": [
        {
          "name": "models/gemini-2.5-pro",
          "version": "001",
          "displayName": "Gemini 2.5 Pro",
          "description": "Google's flagship multimodal reasoning model",
          "inputTokenLimit": 1048576,
          "outputTokenLimit": 8192,
          "supportedGenerationMethods": ["generateContent", "countTokens"]
        },
        {
          "name": "models/gemini-3.1-pro-preview",
          "version": "preview",
          "displayName": "Gemini 3.1 Pro Preview",
          "inputTokenLimit": 1048576,
          "outputTokenLimit": 8192,
          "supportedGenerationMethods": ["generateContent", "countTokens"]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## 응답 필드

### OpenAI 형식

| Field             | Type    | Description                             |
| ----------------- | ------- | --------------------------------------- |
| `object`          | string  | 항상 `list`                               |
| `data`            | array   | 모델 목록                                   |
| `data[].id`       | string  | 모델 식별자; 요청의 `model` 매개변수로 사용            |
| `data[].object`   | string  | 항상 `model`                              |
| `data[].created`  | integer | 출시 타임스탬프(Unix 초)                        |
| `data[].owned_by` | string  | 제공자, 예: `openai`, `anthropic`, `google` |

### Anthropic 형식

| Field                  | Type    | Description         |
| ---------------------- | ------- | ------------------- |
| `data`                 | array   | 모델 목록               |
| `data[].type`          | string  | 항상 `model`          |
| `data[].id`            | string  | 모델 식별자              |
| `data[].display_name`  | string  | 사람이 읽기 쉬운 이름        |
| `data[].created_at`    | string  | 출시 시간(ISO 8601 문자열) |
| `has_more`             | boolean | 추가 페이지 존재 여부        |
| `first_id` / `last_id` | string  | 페이지네이션 커서           |

### Gemini 형식

| Field                                 | Type    | Description              |
| ------------------------------------- | ------- | ------------------------ |
| `models`                              | array   | 모델 목록                    |
| `models[].name`                       | string  | 리소스 이름, 형식 `models/{id}` |
| `models[].displayName`                | string  | 사람이 읽기 쉬운 이름             |
| `models[].description`                | string  | 모델 설명                    |
| `models[].inputTokenLimit`            | integer | 최대 입력 토큰 수               |
| `models[].outputTokenLimit`           | integer | 최대 출력 토큰 수               |
| `models[].supportedGenerationMethods` | array   | 이 모델이 지원하는 메서드           |

## 오류 처리

| Status | Meaning             | Suggested action          |
| ------ | ------------------- | ------------------------- |
| `200`  | 성공                  | —                         |
| `401`  | API 키가 유효하지 않거나 만료됨 | 키를 확인하고 비활성화되지 않았는지 확인    |
| `429`  | 요청이 너무 많음           | 백오프 후 재시도; 할당량 증가는 BD에 문의 |
| `500`  | 내부 서버 오류            | 잠시 후 재시도; 지속되면 지원팀에 문의    |

오류 응답 예시(OpenAI 형식):

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

## 모범 사례

<Tip>
  * **결과 캐싱** — 모델 목록은 자주 바뀌지 않으므로 1시간 이상 캐싱하면 불필요한 요청을 줄일 수 있습니다.
  * **시작 시 검증** — 부팅 시 한 번 호출하여 키가 유효하고 대상 모델을 사용할 수 있는지 확인하세요.
  * **권한 인식** — 반환 목록은 API 키 권한에 따라 달라지며, 키마다 다른 모델이 표시될 수 있습니다.
  * **SDK 즉시 사용** — 공식 OpenAI / Anthropic / Google SDK를 사용할 때 base URL을 `https://api.gravitex.ai`로 지정하면 추가 어댑터 없이 동작합니다.
</Tip>

<Note>
  Python 예시 의존성:

  * OpenAI 형식: `pip install openai`
  * Anthropic 형식: `pip install anthropic`
  * Gemini 형식: `pip install requests`
</Note>