계정 (잔액/사용량/한도)

크레딧 잔액과 사용량을 조회하고, 사용량 한도를 설정하는 API입니다.

잔액 조회

GET/v1/account/balance

조직의 크레딧 잔액을 조회합니다.

Response Body (200 OK)

balancenumber필수

현재 크레딧 잔액 (원)

totalChargednumber필수

누적 충전 금액 (원)

totalConsumednumber필수

누적 소비 금액 (원). 환불 차감 후 순수 소비액입니다.

요청 예시

cURL
Node.js
Python

curl https://api.aiconbiz.kr/v1/account/balance \
  -u "live_sk_your_key_here:"

const secretKey = 'live_sk_your_key_here';
const encoded = Buffer.from(`${secretKey}:`).toString('base64');

const res = await fetch('https://api.aiconbiz.kr/v1/account/balance', {
  headers: {
    'Authorization': `Basic ${encoded}`,
  },
});
const data = await res.json();
console.log(data.balance); // 850000

import base64
import requests

secret_key = "live_sk_your_key_here"
encoded = base64.b64encode(f"{secret_key}:".encode()).decode()

res = requests.get(
    "https://api.aiconbiz.kr/v1/account/balance",
    headers={"Authorization": f"Basic {encoded}"},
)
data = res.json()
print(data["balance"])  # 850000

응답 예시

{
  "balance": 850000,
  "totalCharged": 1000000,
  "totalConsumed": 150000
}

에러 응답

코드	HTTP	설명
`CREDIT_ACCOUNT_NOT_FOUND`	402	크레딧 계정이 활성화되지 않았습니다.

사용량 조회

GET/v1/account/usage

조직의 일일/월간 사용량과 한도를 조회합니다.

Response Body (200 OK)

dailyobject필수

일일 사용량

periodstring필수

기간 키 (KST 기준, YYYY-MM-DD)

usedAmountnumber필수

오늘 사용 금액 (원)

limitAmountnumber | null필수

일일 한도 금액 (원). null이면 한도 없음

remainingAmountnumber | null필수

잔여 한도 (원). null이면 한도 없음

monthlyobject필수

월간 사용량

periodstring필수

기간 키 (KST 기준, YYYY-MM)

usedAmountnumber필수

이번 달 사용 금액 (원)

limitAmountnumber | null필수

월간 한도 금액 (원). null이면 한도 없음

remainingAmountnumber | null필수

잔여 한도 (원). null이면 한도 없음

요청 예시

cURL
Node.js
Python

curl https://api.aiconbiz.kr/v1/account/usage \
  -u "live_sk_your_key_here:"

const secretKey = 'live_sk_your_key_here';
const encoded = Buffer.from(`${secretKey}:`).toString('base64');

const res = await fetch('https://api.aiconbiz.kr/v1/account/usage', {
  headers: {
    'Authorization': `Basic ${encoded}`,
  },
});
const data = await res.json();
console.log(data.daily.remainingAmount);  // 650000
console.log(data.monthly.remainingAmount); // null (한도 없음)

import base64
import requests

secret_key = "live_sk_your_key_here"
encoded = base64.b64encode(f"{secret_key}:".encode()).decode()

res = requests.get(
    "https://api.aiconbiz.kr/v1/account/usage",
    headers={"Authorization": f"Basic {encoded}"},
)
data = res.json()
print(data["daily"]["remainingAmount"])   # 650000
print(data["monthly"]["remainingAmount"]) # None (한도 없음)

응답 예시

{
  "daily": {
    "period": "2026-04-06",
    "usedAmount": 350000,
    "limitAmount": 1000000,
    "remainingAmount": 650000
  },
  "monthly": {
    "period": "2026-04",
    "usedAmount": 2500000,
    "limitAmount": null,
    "remainingAmount": null
  }
}

한도가 설정되지 않은 경우

limitAmount와 remainingAmount가 null이면 해당 기간의 사용 한도가 설정되지 않은 것입니다. 아래 사용량 한도 설정 API로 한도를 설정할 수 있습니다.

에러 응답

이 엔드포인트에는 전용 에러 코드가 없습니다. 인증, 요청 형식 관련 공통 에러가 발생할 수 있습니다.

사용량 한도 설정

PUT/v1/account/usage/limits

일일/월간 사용량 한도를 설정하거나 해제합니다.

Request Body

요청 파라미터

dailyLimitEnabledboolean필수

일일 한도 활성화 여부

dailyLimitAmountnumber | null필수

일일 한도 금액 (원). dailyLimitEnabled가 true이면 필수 (양의 정수).

monthlyLimitEnabledboolean필수

월간 한도 활성화 여부

monthlyLimitAmountnumber | null필수

월간 한도 금액 (원). monthlyLimitEnabled가 true이면 필수 (양의 정수).

한도 활성화 시 금액 필수

dailyLimitEnabled가 true이면 dailyLimitAmount는 null이 될 수 없습니다. monthlyLimitEnabled도 동일합니다.

Response Body (200 OK)

dailyobject필수

일일 한도 설정

limitEnabledboolean필수

한도 활성화 여부

limitAmountnumber | null필수

한도 금액 (원). 미설정 시 null

monthlyobject필수

월간 한도 설정

limitEnabledboolean필수

한도 활성화 여부

limitAmountnumber | null필수

한도 금액 (원). 미설정 시 null

요청 예시

cURL
Node.js
Python

# 한도 설정
curl -X PUT https://api.aiconbiz.kr/v1/account/usage/limits \
  -u "live_sk_your_key_here:" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyLimitEnabled": true,
    "dailyLimitAmount": 1000000,
    "monthlyLimitEnabled": true,
    "monthlyLimitAmount": 5000000
  }'

# 한도 해제
curl -X PUT https://api.aiconbiz.kr/v1/account/usage/limits \
  -u "live_sk_your_key_here:" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyLimitEnabled": false,
    "dailyLimitAmount": null,
    "monthlyLimitEnabled": false,
    "monthlyLimitAmount": null
  }'

const secretKey = 'live_sk_your_key_here';
const encoded = Buffer.from(`${secretKey}:`).toString('base64');

const res = await fetch('https://api.aiconbiz.kr/v1/account/usage/limits', {
  method: 'PUT',
  headers: {
    'Authorization': `Basic ${encoded}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dailyLimitEnabled: true,
    dailyLimitAmount: 1000000,
    monthlyLimitEnabled: true,
    monthlyLimitAmount: 5000000,
  }),
});
const data = await res.json();
console.log(data.daily.limitEnabled);  // true
console.log(data.daily.limitAmount);   // 1000000

import base64
import requests

secret_key = "live_sk_your_key_here"
encoded = base64.b64encode(f"{secret_key}:".encode()).decode()

res = requests.put(
    "https://api.aiconbiz.kr/v1/account/usage/limits",
    headers={
        "Authorization": f"Basic {encoded}",
        "Content-Type": "application/json",
    },
    json={
        "dailyLimitEnabled": True,
        "dailyLimitAmount": 1000000,
        "monthlyLimitEnabled": True,
        "monthlyLimitAmount": 5000000,
    },
)
data = res.json()
print(data["daily"]["limitEnabled"])   # True
print(data["daily"]["limitAmount"])    # 1000000

응답 예시

{
  "daily": {
    "limitEnabled": true,
    "limitAmount": 1000000
  },
  "monthly": {
    "limitEnabled": true,
    "limitAmount": 5000000
  }
}

에러 응답

이 엔드포인트에는 전용 에러 코드가 없습니다. 인증, 요청 형식 관련 공통 에러가 발생할 수 있습니다.

잔액 조회​

Response Body (200 OK)​

요청 예시​

응답 예시​

에러 응답​

사용량 조회​

Response Body (200 OK)​

요청 예시​

응답 예시​

에러 응답​

사용량 한도 설정​

Request Body​

요청 파라미터

Response Body (200 OK)​

요청 예시​

응답 예시​

에러 응답​

잔액 조회

Response Body (200 OK)

요청 예시

응답 예시

에러 응답

사용량 조회

Response Body (200 OK)

요청 예시

응답 예시

에러 응답

사용량 한도 설정

Request Body

Response Body (200 OK)

요청 예시

응답 예시

에러 응답