> ## 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 키의 잔액과 사용량을 조회합니다

## 엔드포인트 정보

| 항목 | 설명 |
| - | - |
| 기본 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/balance
```

응답 구조는 자격 증명에 따라 달라집니다. `data.type`으로 구분할 수 있습니다.

### 3.1 시스템 액세스 토큰으로 계정 잔액 조회 (`type = account`)

| 필드 | 유형 | 설명 |
| - | - | - |
| `type` | string | 고정값 `account` |
| `username` | string | 계정 사용자 이름 |
| `group` | string | 계정 그룹 |
| `currency` | string | 고정값 `USD` |
| `balance` | string | 남은 잔액 |
| `usedAmount` | string | 사용 금액 |
| `totalAmount` | string | 총액 (잔액과 사용 금액의 합) |

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "type": "account",
    "username": "demo_user",
    "group": "default",
    "currency": "USD",
    "balance": "986.9275",
    "usedAmount": "213.0725",
    "totalAmount": "1200.0000"
  }
}
```

> 기업 하위 계정은 해당 계정의 잔액만 조회할 수 있습니다.

### 3.2 API 키로 해당 키의 한도 조회 (`type = token`)

| 필드 | 유형 | 설명 |
| - | - | - |
| `type` | string | 고정값 `token` |
| `tokenName` | string | 키 이름 |
| `group` | string | 키 그룹입니다. 값이 비어 있으면 계정 그룹을 따릅니다. |
| `unlimited` | boolean | 키 한도의 무제한 여부 |
| `currency` | string | 고정값 `USD` |
| `balance` | string | 해당 키의 남은 사용 가능 금액 |
| `usedAmount` | string | 해당 키의 사용 금액 |
| `totalAmount` | string | 키의 총한도 (잔액과 사용 금액의 합) |
| `expiresAt` | integer | 만료 시각의 초 단위 타임스탬프입니다. `0`은 만료되지 않음을 나타냅니다. |
| `modelLimitsEnabled` | boolean | 모델 제한 활성화 여부 |
| `modelLimits` | string\[] | 해당 키로 호출할 수 있는 모델입니다. 제한이 비활성화되면 빈 배열을 반환합니다. |

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "type": "token",
    "tokenName": "my-key",
    "group": "",
    "unlimited": false,
    "currency": "USD",
    "balance": "100.0000",
    "usedAmount": "50.0000",
    "totalAmount": "150.0000",
    "expiresAt": 0,
    "modelLimitsEnabled": false,
    "modelLimits": []
  }
}
```

> `unlimited = true`인 키에는 키 단위 한도가 없으므로 `balance`가 음수일 수 있습니다. 키 사용량은 `usedAmount`로 확인하고, 실제 사용 가능 금액은 계정 잔액을 기준으로 판단하세요.

***

## 4. 요청 예시

```bash theme={null}
# 시스템 액세스 토큰으로 계정 잔액 조회
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
  -H "Authorization: Bearer <access_token>"

# API 키로 해당 키의 한도 조회
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"
```

***

## 5. 참고 사항

1. **갱신 주기.** 잔액 데이터는 약 1분 이내에 갱신됩니다. 충전이나 사용 내역이 반영되기까지 시간이 걸릴 수 있습니다.
2. **최종 청구 금액.** 이 엔드포인트는 조회 및 추정용입니다. 최종 청구 금액은 청구서를 확인하세요.
3. **자격 증명 보호.** 시스템 액세스 토큰으로 계정 전체 정보를 조회할 수 있으므로 외부에 공개하지 마세요. 특정 키의 한도만 조회하려면 해당 API 키를 사용하세요.


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