> ## 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.

# 모델 가격 조회

> 사용 가능한 모델, 그룹 할인, 기본 가격 및 지원 엔드포인트를 조회합니다

## 엔드포인트 정보

| 항목 | 설명 |
| - | - |
| 기본 URL | `https://maas.gravitex.ai/prod-api` |
| 데이터 형식 | `application/json` |
| 문자 인코딩 | `UTF-8` |
| 프로토콜 | `HTTPS` (필수) |
| 통화 | `USD` (미국 달러) |

이 엔드포인트에는 요청 매개변수가 없습니다. 요청마다 인증 헤더를 포함하세요.

## 1. 인증

HTTP 헤더에 Bearer 자격 증명을 포함하세요. **다음 두 가지 중 하나를 사용하세요.**

| 자격 증명 | 발급 위치 | 조회 범위 |
| - | - | - |
| 시스템 액세스 토큰 | 콘솔 → 개인 설정 → 시스템 액세스 토큰 | 계정 전체 |
| API 키 | 콘솔 → 토큰 관리. 일반적으로 `sk-`로 시작합니다. | 해당 키만 |

| 헤더 | 필수 여부 | 설명 |
| - | - | - |
| `Authorization` | 예 | `Bearer <credential>` 형식으로 위 자격 증명 중 하나를 사용합니다. |

```http theme={null}
# 방법 1. 시스템 액세스 토큰
Authorization: Bearer <access_token>

# 방법 2. API 키
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
```

자격 증명이 누락되었거나 유효하지 않거나 삭제 또는 비활성화된 경우, 또는 계정이 비활성화된 경우 인증에 실패합니다.

***

## 2. 공통 응답 구조

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": { }
}
```

| 필드 | 유형 | 설명 |
| - | - | - |
| `code` | integer | 애플리케이션 상태 코드입니다. `200`은 성공을 나타냅니다. |
| `msg` | string | 상태 메시지 |
| `data` | object | 응답 데이터입니다. 실패하면 `null`을 반환합니다. |

### 애플리케이션 상태 코드

| 코드 | 설명 |
| - | - |
| 200 | 성공 |
| 401 | 인증 실패 (자격 증명 누락, 유효하지 않음 또는 비활성화) |

> 요청 성공 여부는 응답 본문의 `code`로 확인하세요.

### 금액 형식

* 모든 금액은 **미국 달러(USD)** 기준이며 부동소수점 정밀도 손실을 방지하기 위해 **문자열**로 반환됩니다.
* 잔액 관련 금액은 항상 **소수점 이하 네 자리**로 표시됩니다. 예를 들어 `"986.9275"`입니다.
* 모델 단가는 소수점 이하 자릿수를 0으로 채우지 않습니다. 예를 들어 `"40"`, `"2.5"`, `"0.00075"`입니다.

***

## 3. 모델 가격 조회

```
GET /api/account/pricing
```

### 3.1 자격 증명별 조회 범위

| 자격 증명 | 반환되는 그룹 | 반환되는 모델 |
| - | - | - |
| 시스템 액세스 토큰 | 계정에서 사용 가능한 모든 그룹 | 계정에서 사용 가능한 그룹의 모든 모델 |
| API 키 | 해당 키에 할당된 그룹 | 키 그룹의 모델입니다. 모델 제한이 활성화된 경우 허용된 모델만 반환됩니다. |

### 3.2 `data` 필드

| 필드 | 유형 | 설명 |
| - | - | - |
| `currency` | string | 고정값 `USD` |
| `tokenUnit` | string | 고정값은 `million`입니다. 토큰 단가는 100만 토큰 기준입니다. |
| `groups` | object\[] | 사용 가능한 그룹 및 할인입니다. 3.3절을 참고하세요. |
| `supportedEndpoint` | object | 반환된 모델이 지원하는 엔드포인트 유형과 요청 경로입니다. 3.4절을 참고하세요. |
| `models` | object\[] | 사용 가능한 모델과 가격입니다. 3.5절을 참고하세요. |
| `tokenName` | string | 현재 API 키 이름입니다. API 키를 사용한 경우에만 반환됩니다. |

### 3.3 `groups` (그룹 및 할인)

| 필드 | 유형 | 설명 |
| - | - | - |
| `group` | string | 그룹 식별자 |
| `desc` | string | 그룹 설명 |
| `ratio` | number | 그룹 가격 배율입니다. 예를 들어 `0.86`이면 기본 가격의 86%가 청구됩니다. |

> `auto` 그룹은 요청을 실제로 처리한 그룹의 배율로 과금됩니다. `auto`의 `ratio`는 참고용입니다.

### 3.4 `supportedEndpoint` (엔드포인트 유형)

각 키는 엔드포인트 유형이며 값은 해당 유형의 요청 메서드와 경로를 나타냅니다.

```json theme={null}
{
  "openai":          { "method": "POST", "path": "/v1/chat/completions" },
  "anthropic":       { "method": "POST", "path": "/v1/messages" },
  "openai-response": { "method": "POST", "path": "/v1/responses" },
  "gemini":          { "method": "POST", "path": "/v1beta/models/{model}:generateContent" }
}
```

이 객체에는 반환된 모델이 사용하는 엔드포인트 유형만 포함됩니다. 모델의 `supportedEndpointTypes`에 나열된 유형으로 요청 경로를 찾을 수 있습니다.

### 3.5 `models` (모델 및 가격)

| 필드 | 유형 | 설명 |
| - | - | - |
| `modelName` | string | 요청의 `model` 매개변수에 지정할 모델 이름 |
| `vendorName` | string | 모델 공급자 |
| `billingType` | integer | 과금 유형입니다. 3.8절을 참고하세요. |
| `enableGroups` | string\[] | 모델을 호출할 수 있는 그룹 |
| `supportedEndpointTypes` | string\[] | 지원하는 엔드포인트 유형입니다. `supportedEndpoint`에서 경로를 확인할 수 있습니다. |
| `billingMode` | string | 구간별로 과금되는 모델에만 반환되며 고정값은 `tiered_expr`입니다. |
| `tierBasis` | string\[] | 과금 구간을 결정하는 기준입니다. 구간별 과금 모델에만 반환됩니다. 3.7절을 참고하세요. |
| `prices` | object | 가격 항목을 키, 단가를 값으로 하는 모델 기본 가격입니다. 3.6절을 참고하세요. |
| `pricingConfig` | object | 일부 이미지, 동영상 및 옴니모달 모델에 반환되는 상세 과금 설정입니다. 3.8절을 참고하세요. |

### 3.6 `prices` (가격 항목)

**토큰 기준 과금** (100만 토큰당 USD)

| 가격 항목 | 설명 |
| - | - |
| `textInputTokens` | 텍스트 입력 |
| `textOutputTokens` | 텍스트 출력 |
| `cacheTokens` | 캐시 읽기 (캐시 적중) |
| `cacheCreationTokens5m` | 캐시 쓰기 (5분) |
| `cacheCreationTokens1h` | 캐시 쓰기 (1시간) |
| `imageInputTokens` | 이미지 입력 |
| `imageOutputTokens` | 이미지 출력 |
| `audioInputTokens` | 오디오 입력 |
| `audioOutputTokens` | 오디오 출력 |
| `videoInputTokens` | 동영상 입력 |
| `videoOutputTokens` | 동영상 출력 |

**요청, 초 또는 이미지 기준 과금**

| 가격 항목 | 단위 |
| - | - |
| `perRequest` | 요청당 USD |
| `seconds` | 초당 USD |
| `imageCount` | 이미지당 USD |

**구간별 가격 항목**은 위 키에 구간 접미사를 붙입니다. 텍스트 입력은 `text` 접두사를 생략하여 `inputTokens`를 사용합니다.

| 접미사 | 의미 | 예시 |
| - | - | - |
| `Lte` | 이하 | `inputTokensLte272K`는 입력이 272K 이하일 때 적용됩니다 |
| `Lt` | 미만 | `inputTokensLt200K` |
| `Gte` | 이상 | `inputTokensGte200K` |
| `Gt` | 초과 | `textOutputTokensGt272K`는 272K 초과 구간의 출력 단가입니다 |
| 범위 | 하한 뒤에 상한 표기 | `inputTokensGt32KLte128K`는 32K 초과 128K 이하 범위입니다 |
| `Peak` / `OffPeak` | 피크 / 비피크 시간대 | `inputTokensPeak`, `inputTokensOffPeak` |

`K`는 1천 토큰, `M`은 100만 토큰을 뜻합니다. 예를 들어 `272K`는 272,000토큰이고 `1M`은 1,000,000토큰입니다.

### 3.7 `tierBasis` (과금 구간 결정 기준)

`Lte272K`처럼 같은 접미사를 사용해도 모델마다 구간 결정 기준이 다를 수 있습니다. 적용 기준은 `tierBasis`에서 확인하세요.

| tierBasis | 기준 | 구간을 결정하는 값 |
| - | - | - |
| `context` | 컨텍스트 길이 | 캐시 적중분을 포함한 전체 입력 컨텍스트 길이 |
| `input` | 입력 | 캐시, 이미지, 오디오 등 별도 과금 항목을 제외한 텍스트 입력 토큰 |
| `output` | 출력 | 해당 요청의 출력 토큰 |
| `time` | 시간대 | 요청 시각 (베이징 시간) |

**과금 규칙**

1. **요청 전체에 하나의 구간을 적용합니다.** 요청의 사용량으로 구간을 결정하며, 입력, 출력, 캐시 등 모든 항목에 해당 구간의 단가를 적용합니다. 구간별 누진 과금은 적용되지 않습니다.
   * `tierBasis = ["context"]`인 모델에서 컨텍스트가 300K이면 `Gt272K` 구간에 해당합니다. 입력, 출력, 캐시에 각각 해당하는 `xxxGt272K` 단가가 적용됩니다.
2. **컨텍스트 길이에는 캐시 적중분이 포함됩니다.** 텍스트 입력에서는 캐시 적중분을 제외합니다.
   * 새 입력 200K와 캐시 적중 100K가 있으면 컨텍스트 길이는 300K(`Gt272K`), 텍스트 입력은 200K(`Lte272K`)입니다.
3. `["input", "output"]`처럼 **기준이 여러 개라면 모든 조건을 충족해야** 해당 구간이 적용됩니다.
4. **시간대별 과금**에는 두 가지 방식이 있습니다.
   * `prices`에 피크 및 비피크 시간대의 `xxxPeak`와 `xxxOffPeak` 단가가 모두 표시됩니다.
   * `prices`에는 기본 단가만 표시되며 피크 시간에는 배율이 적용됩니다. 구체적인 시간대와 배율은 계정 담당자에게 문의하세요.

### 3.8 `billingType` (과금 유형)

| billingType | 설명 | prices | pricingConfig |
| - | - | - | - |
| 0 | 토큰 기준 | 토큰 가격 항목이며 구간별 과금 모델에는 접미사가 붙습니다 | 없음 |
| 1 | 요청 기준 | `perRequest` | 없음 |
| 2 | 이미지 토큰 기준 | 비어 있음 | 이미지 토큰 항목별 단가 (100만 토큰당 USD) |
| 3 | 동영상 초 기준 | 단일 단가인 경우 `seconds` | 해상도, 오디오 포함 여부 등에 따른 단가 |
| 4 | 옴니모달 과금 | 비어 있음 | 텍스트, 이미지, 오디오 등 항목별 단가 |
| 5 | 이미지 장수 기준 | 단일 단가인 경우 `imageCount` | 참조 이미지 수, 출력 크기 등에 따른 단가 |
| 6 | 동영상 토큰 기준 | 토큰 가격 항목 (`videoOutputTokens` 포함) | 해상도, 동영상 입력 포함 여부 등에 따른 단가 |

> `pricingConfig` 구조는 모델마다 다릅니다. 실제 설정은 API 응답을 확인하세요.

### 3.9 실제 적용 단가

```
실제 적용 단가 = prices의 기본 가격 × 사용한 그룹의 ratio
```

`textInputTokens`가 `"8"`인 모델을 `ratio = 0.86`인 그룹에서 호출하면 실제 입력 단가는 8 × 0.86 = **100만 토큰당 6.88달러**입니다.

### 3.10 응답 예시

다음은 응답의 일부를 보여 주는 예시입니다.

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "currency": "USD",
    "tokenUnit": "million",
    "groups": [
      { "group": "default",   "desc": "默认分组",  "ratio": 1.0 },
      { "group": "auto",      "desc": "自动",      "ratio": 1.0 },
      { "group": "Anthropic", "desc": "Anthropic", "ratio": 0.86 }
    ],
    "supportedEndpoint": {
      "openai":          { "method": "POST", "path": "/v1/chat/completions" },
      "anthropic":       { "method": "POST", "path": "/v1/messages" },
      "openai-response": { "method": "POST", "path": "/v1/responses" }
    },
    "models": [
      {
        "modelName": "claude-fable-5-2",
        "vendorName": "Anthropic",
        "billingType": 0,
        "enableGroups": ["Anthropic", "default"],
        "supportedEndpointTypes": ["openai", "anthropic"],
        "prices": {
          "textInputTokens": "8",
          "textOutputTokens": "40",
          "cacheTokens": "0.2",
          "cacheCreationTokens5m": "10"
        }
      },
      {
        "modelName": "gpt-5.4",
        "vendorName": "OpenAI",
        "billingType": 0,
        "enableGroups": ["default"],
        "supportedEndpointTypes": ["openai", "openai-response"],
        "billingMode": "tiered_expr",
        "tierBasis": ["context"],
        "prices": {
          "inputTokensLte272K": "2.5",
          "textOutputTokensLte272K": "15",
          "cacheTokensLte272K": "0.25",
          "inputTokensGt272K": "5",
          "textOutputTokensGt272K": "22.5",
          "cacheTokensGt272K": "0.5"
        }
      },
      {
        "modelName": "grok-imagine-image",
        "vendorName": "xAI",
        "billingType": 1,
        "enableGroups": ["default"],
        "supportedEndpointTypes": ["openai-images"],
        "prices": { "perRequest": "0.02" }
      }
    ]
  }
}
```

API 키를 사용하면 `groups`에는 해당 키의 그룹만, `models`에는 해당 그룹에서 사용 가능한 모델만 포함됩니다. 응답에 `tokenName`도 추가됩니다.

***

## 4. 요청 예시

```bash theme={null}
# 모델 가격 조회
curl -s "https://maas.gravitex.ai/prod-api/api/account/pricing" \
  -H "Authorization: Bearer <access_token>"
```

***

## 5. 참고 사항

1. **갱신 주기.** 모델 가격 변경은 약 1분 이내에 적용됩니다.
2. **기본 가격.** `prices`의 모델 기본 가격에 사용한 그룹의 `ratio`를 곱하면 실제 적용 단가를 계산할 수 있습니다.
3. **최종 청구 금액.** 이 엔드포인트는 조회 및 추정용입니다. 최종 청구 금액은 청구서를 확인하세요.
4. **자격 증명 보호.** 시스템 액세스 토큰으로 계정 전체 정보를 조회할 수 있으므로 외부에 공개하지 마세요. 특정 키의 한도만 조회하려면 해당 API 키를 사용하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.