요금·잔액
무엇으로 얼마가 빠지고, 잔액이 바닥나면 어떻게 되는지.
어떻게 차감되나
구매한 사용량 패키지에서 사용한 만큼 원화로 빠집니다. 월 정액도, 기본료도 없습니다. 호출이 끝날 때마다 그 호출의 금액이 잔액에서 차감되고, 남은 잔액은 화면 오른쪽 위에 늘 떠 있습니다.
- 쓴 만큼만. 호출하지 않는 달에는 아무것도 빠지지 않습니다.
- 스트리밍도 똑같이 집계됩니다. 중간에 연결이 끊겨도 그때까지 오간 만큼은 차감됩니다 — 받다 만 응답이라고 공짜가 되지는 않습니다.
- 막힌 요청은 과금되지 않습니다.
401·403·429처럼 게이트웨이가 상위로 보내기 전에 막은 호출은 모델을 부르지 않았으니 잔액도 건드리지 않습니다. - 한 계정의 잔액은 키를 나눠 써도 하나입니다. 키를 여러 개 발급해도 잔액은 계정 단위입니다.
같은 문장을 반복해서 임베딩하거나 같은 프롬프트를 매번 다시 부르면 그만큼 그대로 빠집니다. 결과를 저장해 두는 것이 가장 확실한 절약입니다.
충전하기
충전은 충전·결제 화면에서 합니다. 결제가 끝나면 잔액에 바로 더해집니다.
충전·결제 열기
/app/billing 에서 현재 잔액과 지금까지의 충전·차감 내역을 한 화면에서 봅니다.
금액 입력
한 번에 10,000원 ~ 2,000,000원 사이로 구매할 수 있습니다.
결제 후 바로 재개
충전액은 즉시 잔액에 반영됩니다. 잔액이 없어 막혀 있던 호출도 그대로 다시 나가며, 키를 다시 발급할 필요는 없습니다.
바닥나기 전에 알려 드립니다
잔액은 화면 오른쪽 위에 늘 떠 있고, 얼마 남지 않으면 배너로도 알립니다. 자동 결제는 없으니 배너가 뜨면 직접 충전하세요.
잔액이 0원이 되면
호출이 막힙니다. 이때 돌아오는 응답이 429 insufficient_balance 이고, 본문에는 사람이 읽을 수 있는 한 문장(message)과 충전 페이지 주소(topup_url)가 함께 옵니다. 앱에서 이 응답을 어떻게 받아 처리하는지는 오류 처리 에 있습니다.
| 막힌 이유 | error | 푸는 방법 |
|---|---|---|
| 잔액 소진 | insufficient_balance | 충전 하면 즉시 재개됩니다. 응답에 topup_url 이 붙습니다. |
| 키 월 예산 소진 | budget_exceeded | 키에 걸린 월 예산입니다. 충전으로는 풀리지 않아 topup_url 도 없습니다 — 관리자에게 문의해 주세요. |
| 분당 요청 한도 | rate_limited | 잔액과 무관합니다. 잠시 기다렸다 한 번만 다시 보내면 됩니다. |
잔액이 0원이어도 키는 살아 있습니다
막히는 것은 호출이지 키가 아닙니다. 충전 뒤 재발급 없이 쓰던 키를 그대로 쓰면 됩니다. 키를 새로 발급하면 오히려 앱에 박아 둔 키를 전부 바꿔야 합니다.
코드에서 잔액 확인하기
GET /v1/balance 로 지금 잔액을 읽을 수 있습니다. 호출이 429 로 막히고 나서야 아는 대신, 미리 확인해 사용자에게 안내를 띄울 수 있습니다.
curl https://ai.cubion.kr/v1/balance \
-H "Authorization: Bearer $GATEWAY_KEY"import os, httpx
r = httpx.get(
"https://ai.cubion.kr/v1/balance",
headers={"Authorization": f"Bearer {os.environ['GATEWAY_KEY']}"},
)
b = r.json()
if b["balance"] <= 0:
print("잔액이 없습니다:", b["topup_url"])
elif b["low_balance"]:
print("잔액이 얼마 남지 않았습니다:", b["balance"], b["currency"])const r = await fetch("https://ai.cubion.kr/v1/balance", {
headers: { Authorization: `Bearer ${process.env.GATEWAY_KEY}` },
});
const b = await r.json();
if (b.balance <= 0) {
console.warn("잔액이 없습니다:", b.topup_url);
} else if (b.low_balance) {
console.warn("잔액이 얼마 남지 않았습니다:", b.balance, b.currency);
}{
"object": "balance",
"currency": "KRW",
"balance": 12345.67,
"low_balance": false,
"topup_url": "https://ai.cubion.kr/app/billing"
}| 필드 | 설명 |
|---|---|
balance | 남은 잔액. 원 단위이고 소수점 두 자리까지 의미가 있습니다. |
currency | 지금은 KRW 하나뿐입니다. 금액만 보고 단위를 짐작하지 않도록 함께 보냅니다. |
low_balance | 설정된 기준 아래로 내려왔는지. 기준이 꺼져 있으면 항상 false 입니다. |
topup_url | 충전 페이지 주소. 429 insufficient_balance 응답의 topup_url 과 같습니다. |
잔액이 0원이어도 200 으로 답합니다
잔액을 확인하고 싶은 순간이 바로 0원일 때라서, 이 호출만은 잔액 검사에 걸리지 않습니다. 호출 요금도 들지 않고, 분당 한도도 걸리지 않습니다 — 충전이 반영됐는지 몇 초 간격으로 확인해도 됩니다.
스코프와 무관하게 아무 키로나 부를 수 있습니다. 잔액은 키가 아니라 계정에 붙어 있어서, 같은 계정의 어떤 키로 불러도 같은 값이 나옵니다. 관리자가 발급한 키(선불 계정에 묶이지 않은 키)는 404 no_prepaid_balance 를 받습니다.
사용 내역 확인
사용량 에서 기간을 바꿔 가며 모델별·키별 호출 수와 청구 금액을 볼 수 있습니다. 어떤 키가 얼마를 쓰고 있는지 여기서 먼저 확인하세요.
- 사용량 — 기간별 호출 수와 금액, 모델·키별로 나눠 봅니다.
- 충전·결제 — 충전 내역과 차감 내역을 한 건씩 확인합니다.
- 금액이 갑자기 늘었다면 키별 사용량부터 보세요. 유출이 의심되면 API 키 에서 그 키를 폐기하면 즉시 호출이 막힙니다.
집계는 어떤 키가 어떤 모델을 언제 몇 번 불렀고 얼마가 차감됐는지로 쌓입니다. 표의 기간을 좁혀 두면 어제 무엇이 늘었는지가 바로 보입니다.
코드에서 사용량 조회하기
GET /v1/usage 는 호출한 키의 요청 수·토큰·청구 금액(원)을 돌려줍니다. 사내 대시보드에 그대로 그리면 됩니다. 기간은 한국 시간 날짜(YYYY-MM-DD)이고, 생략하면 이번 달 1일부터 오늘까지입니다(최대 92일).
curl "https://ai.cubion.kr/v1/usage?from=2026-09-01&to=2026-09-30&group_by=model,day" \
-H "Authorization: Bearer $GATEWAY_KEY"{
"object": "usage",
"currency": "KRW",
"from": "2026-09-01",
"to": "2026-09-30",
"group_by": "model,day",
"billed_krw_source": "ledger",
"total": { "requests": 1240, "prompt_tokens": 1830211, "completion_tokens": 211904, "billed_krw": 18342.55 },
"data": [
{ "model": "gpt-4.1", "day": "2026-09-01", "requests": 42, "prompt_tokens": 61210, "completion_tokens": 7102, "billed_krw": 612.40 }
]
}| 파라미터 | 설명 |
|---|---|
from · to | 조회 기간(포함). 한국 시간 기준 날짜. |
group_by | model(기본) · day · model,day |
금액은 청구 기준 원화뿐입니다. 선불 계정 키는 잔액에서 실제로 빠진 금액(billed_krw_source: "ledger"), 관리자가 발급한 키는 같은 요금 공식으로 계산한 금액("policy")입니다. 키마다 따로 집계되므로 용도별로 키를 나눠 쓰면 용도별 비용이 됩니다. 잔액 조회와 마찬가지로 호출 요금·분당 한도가 걸리지 않습니다.