요약: API 키에 할당량을 설정해도 비용은 여전히 예상을 초과할 수 있어요. 이 글에서는 그 이유를 설명하고, AI 체험용 예산 관리를 순서가 있는 세 개의 예산선으로 나눠 살펴봐요.
먼저 결론부터 말할게요. 게이트웨이의 Key 할당량은 소프트 상한이며, 동시 요청이 몰리는 상황에서는 하드 청구 상한으로 쓸 수 없어요. APIYI의 토큰 문서를 예로 들면, 할당량은 요청이 시작되는 시점에 검사돼요. 여러 요청이 동시에 검사를 통과하거나, 단일 요청 자체의 가격이 아주 높으면 최종 소비는 설정한 할당량을 넘어설 수 있어요.
신뢰할 수 있는 방법은 세 계층으로 나눠 처리하는 거예요:
- 애플리케이션 백엔드가 요청을 보내기 전에 검사를 마치고, 원자적으로 예산을 예약해요.
- 게이트웨이 쪽에서는 체험 트래픽용으로 별도의 Key를 발급하고, 할당량과 모델 화이트리스트를 함께 붙여서 이 Key가 남용됐을 때의 영향 범위를 좁혀요.
- 계정 잔액 알림은 오직 통지만 담당하며, 사람이 대응하도록 신호를 보내는 역할이에요.
이 세 계층의 역할은 서로를 대체할 수 없어요. 진짜 예산 진입은 애플리케이션 자신의 원장에서 일어나요.

지식 지도와 인덱스: 세 가지 예산선의 적용 순서와 역할 분담
아래 표는 지식 지도이자 인덱스 역할도 해요. 세 가지 예산선이 어떤 순서로 적용되는지, 각각 무엇을 담당하는지, 왜 이렇게 배치했는지, 그리고 본문의 어느 부분과 연결되는지를 한눈에 보여 줘요.
| 순서 | 예산선 | 담당하는 것 | 이 위치에 둔 이유 | 목표 | 본문 |
|---|---|---|---|---|---|
| 전제 | 소프트 한도 이해 | 요청 전 검사, 사전 차감, 실제 차감 구분 | 과금 시점을 모르면 뒤의 세 계층을 설계할 수 없어요 | 초과 지출이 어떻게 발생하는지 이해 | 1, 1.1 |
| 1차 | 애플리케이션 백엔드 예산 | 사용자와 트라이얼 풀 기준으로 원자적 예약과 정산 수행 | 누가 쓰고 있는지, 얼마나 쓸 수 있는지는 애플리케이션만 알아요 | 요청을 보내기 전에 초과 지출을 차단 | 2.1, 3 |
| 2차 | 독립 트라이얼 Key | 할당량, 모델 허용 목록, 정식 트래픽과의 격리 | 애플리케이션에 버그가 생겼을 때 게이트웨이가 두 번째 경계 역할을 해요 | 단일 Key의 노출 범위를 줄임 | 2.2, 3 |
| 3차 | 계정 잔액 알림 | 잔액이 임곗값보다 낮아지면 알림 | 알림은 사후 신호일 뿐 차단 기능은 없어요 | 사람이 제때 개입할 수 있게 함 | 2.3 |
| 적용 | 동시성 원장과 출시 전 점검 | 예약, 정산, 실패 처리, 대조, 친절한 안내 | 앞선 원칙을 검증 가능한 프로세스로 구현 | 출시 전에 항목별로 검수할 수 있음 | 3, 4 |
읽는 순서는 이렇게 권해요. 먼저 1절에서 타이밍을 이해하고, 2절에서 역할 분담을 확인한 뒤, 3절에서 구현 내용을 보세요. 4절은 출시 전에 따로 대조해 보기 좋아요.
알아두기: 예산선을 이해하기 전에 필요한 용어
| 용어 | 간단한 설명 |
|---|---|
| 소프트 상한 | 요청 시작 시 잔여额度을 확인하지만, 통과했다고 해서 총소비가 선을 넘지 않는다는 보장은 없음 |
| 예약 차감 | 게이트웨이가 추정치를 기준으로 먼저 일정 额度을 차감하고, 요청 종료 후 실제 사용량대로 정산 |
| 원자적 예약 | 단일 분할 불가능한 작업으로 ‘잔여분 확인 + 점유’를 완료하여 동시 요청이 함께 통과하는 것을 방지 |
| 처리 중 예약 | 요청은 이미 나갔지만 실제 비용이 확정되지 않은 상태로, 원장에 여전히 점유 상태로 남아 있는 예산 부분 |
| remain_quota | APIYI 토큰의 일회성 총 额度 필드로, 문서 기준 500000이 $1에 해당 |
| 대사(對賬) | 게이트웨이 로그와 자체 원장을 항목별로 대조하여 추정과 실제 사이의 편차를 수정 |
1. API 키 额度이 동시 요청으로 초과될 수 있는 이유
APIYI 토큰 문서는 이 점을 명확히 적고 있어요. Key 额度은 소프트 상한이며, 요청 시작 시점에 검사한다는 것입니다. 그래서 동시 요청이나 단일 고비용 요청이 실제 소비를 설정된 额度 이상으로 끌어올릴 수 있어요. 이는 ‘시작 시 검사, 종료 시 정산’이라는 과금 구조 자체의 특성이지, 어느 플랫폼에 버그가 있느냐의 문제가 아니에요.
가정 시나리오로 이해해 봐요(숫자는 모두 설명용이며 실측값이 아니에요). 체험용 Key의 잔여 额度이 $1에 해당한다고 할 때, 같은 순간에 20개의 요청이 몰린다고 해봐요. 각 요청은 시작 시점에 “잔액이 남아 있다”고 보고 전부 통과돼요. 요청들이 차례로 끝나며 실제 사용량대로 정산되면, 총소비는 이미 $1을 크게 넘어선 상태가 돼요. 동시 요청이 없더라도, 한 번의 긴 컨텍스트 + 대량 출력 요청은 단일 비용만으로도 잔여 额度을 넘길 수 있어요.
흔한 오해 두 가지도 짚고 갈게요:
- 额度은 매일 자동으로 복구되지 않아요. 문서상 remain_quota는 일회성 총 额度이며, “매일 재설정”은 애플리케이션 쪽에서 크론 스크립트를 직접 작성해 구현해야 해요.
- 모델 화이트리스트는 비용 상한이 아니에요. 어떤 모델을 호출할 수 있는지만 제한할 뿐, 같은 모델의 호출 횟수나 매 요청 규모에는 아무런 제약이 없어요.

1.1 API 키 额度의 세 시점: 요청 전 검사, 추정, 실제 차감
한 번의 호출에는 과금상 세 가지 시점이 있고, 각각 대답하는 질문이 달라요:
| 시점 | 위치 | 대답하는 질문 | 하드 상한으로 쓸 수 있는가 |
|---|---|---|---|
| 요청 전 검사 | 게이트웨이, 요청 시작 시점 | 이 Key에 지금 잔여분이 있는가 | 불가능, 동시 요청 시 함께 통과 |
| 추정 및 예약 차감 | 게이트웨이, 추정치 기반 | 이번 요청이 대략 얼마나 점유할지 | 불가능, 추정과 실제에 편차 존재 |
| 실제 차감 | 게이트웨이, 요청 종료 후 | 이번 요청이 실제로 얼마나 썼는지 | 사후 데이터로, 접근 제어에 사용 불가 |
APIYI의 예약 차감 관련 설명은 이렇습니다: 게이트웨이는 추정치를 기반으로 예약 차감하고 사후에 실제 사용량대로 정산하며, 이 메커니즘은 업무 측의 원자적 예약을 대체하지 않습니다. 게이트웨이의 예약 차감은 자체 과금을 위한 것이지, 당신의 특정 사용자가 오늘 체험 额度을 얼마나 남겼는지 알지 못합니다. 따라서 “이 사용자가 요청을 한 번 더 보낼 수 있는가”라는 질문은 애플리케이션 백엔드만이 대답할 수 있습니다.
2 AI 체험의 세 가지 예산선
세 가지 선은 각각 세 종류의 리스크를 겨냥해요. 비즈니스 로직 차원의 초과 사용, Key 차원의 남용이나 유출, 계정 차원의 잔액 소진이에요. OWASP API Security Top 10(2023)의 API4 ‘Unrestricted Resource Consumption’이 다루는 것도 같은 종류의 문제예요. 리소스 소비에 제한을 두지 않은 인터페이스는 서비스와 비용 양쪽에서 리스크를 만들어내죠. AI 인터페이스에서는 비용 리스크가 더 직접적으로 드러나는 경우가 많아요.
2.1 첫 번째 예산선: 애플리케이션 백엔드의 사용자 및 체험 풀 예산
이 계층은 ‘입장 허가’를 할 수 있는 유일한 단계라서, 두 가지 레벨을 관리해야 해요.
- 사용자 레벨 예산: 체험 사용자 한 명당 총 할당량, 혹은 일일 할당량이에요. 일일 할당량은 애플리케이션 자체의 정기 작업으로 리셋하며, 게이트웨이에 의존하지 않아요.
- 체험 풀 예산: 모든 체험 사용자가 공유하는 총 상한이에요. 개별 사용자가 전부 한도 안에 있더라도, 사용자 수가 급증할 때를 대비해 총비용에도 상한이 있어야 하죠.
하나의 요청은 사용자 레벨과 풀 레벨의 예약을 동시에 통과해야만 통과시킬 수 있고, 두 예약은 반드시 같은 원자적 연산이나 같은 트랜잭션 안에서 완료되어야 해요. 그렇지 않으면 “사용자 예약은 성공했는데 풀은 이미 꽉 찬” 경쟁 상태가 생기고 말아요.
이 계층에서는 요청의 규모도 서버 쪽에서 결정해야 해요. 어떤 모델을 허용할지, max_tokens 상한은 얼마인지, 입력 길이는 어디까지 허용할지 같은 것들이죠. 이런 파라미터를 프런트엔드에서 넘겨받아 그대로 전달하면, 사용자가 파라미터 하나만 바꿔도 추정 금액이 틀어져요.
2.2 두 번째 예산선: 독립된 체험 Key, 할당량, 모델 화이트리스트
게이트웨이 쪽에서 체험 트래픽 전용 Key를 따로 발급해서 정식 트래픽과 완전히 격리해요. 이 Key의 역할은 노출 범위를 제한하는 거예요. 애플리케이션 원장에 버그가 생기거나 Key가 유출됐을 때, 손실이 이 Key의 할당량 안으로 제한되고 정식 비즈니스로 번지지 않게 하는 거죠.
설정할 때 주의할 점은 이래요.
- 할당량은 ‘체험 풀 예산 + 약간의 버퍼’로 설정해요. 애플리케이션 쪽 풀 예산보다 살짝 높게 잡아 안전망 역할을 하게 하고, 풀 예산과 똑같이 두지는 마세요. 그렇지 않으면 애플리케이션 계층의 예약이 유명무실해져요.
- 모델 화이트리스트에는 체험에서 개방한 모델만 넣어요. 체험 Key로 고가 모델을 호출하는 걸 막아주지만, 횟수와 규모는 제한하지 못하므로 2.1절에서 말한 서버 쪽 규모 제한은 여전히 필요해요.
- 할당량은 소프트 상한이기 때문에 이 선은 ‘약간의 초과’를 허용해요. 초과 폭을 허용 가능한 범위 안으로 제어하는 데 의미가 있고, 초과 지출 제로를 기대할 수는 없어요.
프로젝트별로 Key, 할당량, 로그를 나누는 일반적인 방식은 별개의 주제이니, 여기서는 한 가지만 강조할게요. 체험 트래픽에는 전용 Key 하나를 쓴다는 것.
2.3 세 번째 예산선: 계정 잔액 알림
APIYI의 잔액 알림 문서에도 알림은 통지일 뿐 요청을 차단하지 않는다고 명확히 나와 있어요. 잔액이 임계값 아래로 떨어지면, 알림은 담당자에게 메시지를 보내는 역할만 하고, 충전할지, 체험 진입점을 잠시 닫을지, 아니면 이상 트래픽을 조사할지는 사람이 결정하죠.
이 계층을 쓸 때 두 가지를 권해요.
- 알림 임계값은 ‘발견부터 처리까지 걸리는 시간 동안의 최대 소비량’을 기준으로 정하세요. 무심코 정수 하나를 넣지 마세요.
- 알림은 구체적인 대응 행동과 연결되어야 해요. 예를 들어 당직 매뉴얼에 “알림을 받으면 우선 체험 등록 진입점을 닫는다”라고 적어두는 식이죠. 알림만 있고 후속 행동이 없는 알림은 유명무실해요.
3 가상의 동시성 원장: 원자적 예약에서 대조까지
이 절에서는 예시 설계를 소개해요. 테이블 구조, 가격, 숫자는 모두 가정한 값이라서 흐름을 설명하기 위한 것이지, 어떤 시스템의 실제 측정 데이터도 아니에요. 흐름은 총 다섯 단계예요:
원자적 확인 및 예약 → 서버가 model과 규모를 확정 → 요청 전송
→ 정산 / 실패 처리 → 오프라인 대조 및 보정

3.1 예산 원장의 테이블 구조와 상태
예시 데이터 구조에는 두 개의 테이블이 있어요. budgets는 사용자별·체험 풀별 상한, 지출액, 예약액을 기록하고, reservations는 예약 한 건 한 건과 그 상태를 기록해요.
| 예약 상태 | 의미 | “사용 가능 잔여량”에 미치는 영향 |
|---|---|---|
| reserved | 예약됨, 요청 처리 중 | 예상 금액만큼 점유 |
| settled | 실제 사용량을 받아 정산 완료 | 지출로 전환되고 차액은 해제 |
| released | 요청이 실행되지 않았음을 확인 | 전액 해제 |
| unknown | 타임아웃, 연결 끊김으로 비용 미확인 | 계속 점유, 대조 대기 |
사용 가능 잔여량은 limit - spent - reserved로 계산하는데, 여기서 reserved에는 unknown 상태의 예약도 포함돼요.
3.2 원자적 검사 및 예약: 동시 요청이 함께 통과하는 것 방지
핵심은 ‘검사’와 ‘점유’를 하나의 조건부 업데이트 문으로 합치고, 데이터베이스가 원자성을 보장하게 하는 것입니다:
-- 예시: 잔여 한도가 충분할 때만 예약하고, 영향받은 행 수를 반환합니다
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
AND limit_amount - spent - reserved >= :estimate;
-- 영향받은 행 수는 반드시 2여야 합니다(사용자와 풀 모두 성공). 그렇지 않으면 트랜잭션을 롤백하고 요청을 거부합니다
예약 금액은 상한값으로 잡아야 합니다: 입력 token 수에 입력 단가를 곱하고, 여기에 max_tokens에 출력 단가를 곱한 값을 더합니다. 실제 사용량은 보통 이보다 적으므로 정산할 때 차액을 돌려주면 됩니다. 조금 더 예약하는 편이, 덜 예약하는 것보다 낫습니다.
3.3 서버 측에서 model과 작업 규모 고정
예약에 사용한 추정 파라미터는 실제로 발송하는 요청 파라미터와 완전히 일치해야 합니다. 예시 코드는 다음과 같습니다:
ALLOWED_TRIAL_MODELS = {"trial-model-a"} # 예시: 체험용으로 공개한 모델
MAX_OUTPUT_TOKENS = 1024 # 예시: 서버 측 강제 상한
MAX_INPUT_TOKENS = 8000
def build_trial_request(user_input, requested_model):
model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
else "trial-model-a"
input_tokens = count_tokens(user_input)
if input_tokens > MAX_INPUT_TOKENS:
raise InputTooLarge()
estimate = price_in(model) * input_tokens \
+ price_out(model) * MAX_OUTPUT_TOKENS
return model, MAX_OUTPUT_TOKENS, estimate
프런트엔드에서 전달된 max_tokens와 model은 참고값일 뿐이며, 최종적으로는 서버 측 결정을 따릅니다.
3.4 요청 전송, 정산, 실패 처리
요청을 보내기 전에 고유한 요청 ID를 하나 생성해서 예약 기록에 써 두면, 나중에 로그에서 매칭하기가 편해요. 요청이 돌아온 뒤에는 세 가지 경우로 나눠 처리합니다.
- 성공하고 usage를 받은 경우: 실제 사용량으로 금액을 계산하고
spent += actual,reserved -= estimate를 적용한 뒤 예약 상태를 settled로 바꿉니다. - 실행되지 않았다고 확실히 알 수 있는 실패: 파라미터 검증 실패, 인증 실패처럼 요청이 과금 단계에 진입하지 않았다고 확인 가능한 오류예요. 이때는 예약을 해제하고 상태를 released로 바꿉니다.
- 타임아웃 또는 연결 중단: 요청이 이미 업스트림에서 실행되어 비용이 발생했을 수도 있는데, 결과만 전달되지 않은 상황이에요. 이때는 비용을 0으로 처리하면 안 되고, 상태를 unknown으로 기록하며 예약은 계속 점유 상태로 둡니다.
3번째 경우가 가장 실수하기 쉬워요. 타임아웃이라고 해서 예약을 바로 해제해 버리면, 이미 발생했을 수도 있는 비용을 장부에서 지워버리는 셈이거요. 동시성이 높고 타임아웃률이 높은 시간대에는 이런 오차가 계속 누적됩니다.
3.5 오프라인 대사: unknown과 추정 편차 보정
APIYI의 로그 조회는 증분 내보내기를 지원하지만, 문서상 용도가 오프라인 대사이기 때문에 요청별 승인 판단의 근거로 쓸 수는 없어요. 그래서 대사는 정기 작업으로 만들어야 합니다.
- 마지막 대사 이후의 증분 로그를 가져와서 요청 ID 또는 시간 윈도우 기준으로
reservations테이블과 매칭해요. - 로그에서 찾을 수 있는 unknown 예약은 로그의 실제 금액으로 settled로 바꾸고, 정해진 시간 윈도우를 넘겨도 기록을 찾을 수 없는 것은 released로 바꿉니다.
- “추정 금액과 실제 금액”의 편차 분포를 집계해요. 실제 금액이 자주 추정치에 가깝거나 심지어 넘어선다면, 3.3절의 추정 공식을 다시 점검해야 합니다.
대사 결과는 동시에 세 번째 예산선에 대한 입력이기도 해요. 장부 합계와 계정의 실제 소비가 계속 맞지 않는다면, 그 자체가 수동 점검이 필요한 신호이거든요.

4 예산 라인 출시 전 점검과 할당량 부족 시 친절한 안내
4.1 세 가지 예산 라인 출시 전 점검표
| 점검 항목 | 해당 예산 라인 | 검증 방법 |
|---|---|---|
| 사용자와 풀의 예약이 동일 트랜잭션 내에서 완료된다 | 1차 | 동시 요청 부하 테스트로 지출과 예약의 합이 상한을 넘지 않는지 확인 |
| model, max_tokens, 입력 길이는 서버에서 결정한다 | 1차 | 프런트엔드 파라미터를 변조해 무효인지 확인 |
| 타임아웃 요청은 unknown으로 기록되고 점유가 유지된다 | 1차 | 타임아웃 장애를 주입하고 원장 상태 확인 |
| 대사 작업이 정기적으로 실행되고 unknown을 처리한다 | 1차 | 대사 로그와 상태 전이 확인 |
| 체험용 Key는 독립적이고 할당량이 풀 예산보다 약간 높다 | 2차 | Key 설정과 풀 예산 수치 대조 |
| 체험용 Key의 모델 화이트리스트에는 체험 모델만 포함된다 | 2차 | 화이트리스트에 없는 모델로 호출해 거부되는지 확인 |
| 일일 할당량 재설정 스크립트가 존재하고 모니터링된다 | 1·2차 | 정기 작업의 실행 기록 확인 |
| 잔액 경고 임계값이 대응 매뉴얼과 일치한다 | 3차 | 경고 발생부터 진입점 차단까지의 절차를 한 번 리허설 |
4.2 할당량 부족 시 사용자 안내
예약에 실패하면 애플리케이션은 명확한 비즈니스 오류를 반환해야 하며, 요청이 게이트웨이까지 도달한 뒤 이해하기 어려운 오류로 보고되게 해서는 안 됩니다. 안내에는 다음 세 가지 정보를 포함하는 것이 좋습니다.
- 무슨 일이 일어났는지: 예를 들어 “오늘의 체험 할당량이 모두 소진되었습니다” 또는 “현재 체험 인원이 가득 찼습니다”처럼, 사용자 할당량 부족과 체험 풀 포화를 구분해 안내해야 합니다.
- 언제 복구되는지: 일일 할당량이 설정되어 있다면 재설정 시간을 알려 주고, 일회성 할당량이 소진된 경우에는 이후 선택 가능한 업그레이드 방법을 설명합니다.
- 현재 상태: 남은 할당량을 표시할 수 있지만 원장의 가용 잔량을 기준으로 해야 하며, 처리 중인 예약을 차감한 상태여야 합니다. “잔액이 있다고 표시됐는데 거부되는” 상황을 피해야 합니다.
위 점검을 마친 뒤에는 간단한 방법으로 전체 예산 라인을 검수할 수 있습니다. 동시 요청 폭주에 업스트림 타임아웃을 겹쳐 시뮬레이션하고, 원장의 “지출 + 처리 중 예약”이 대사 후 실제 소비량 이상으로 항상 유지되는지 확인합니다. 동시에 체험용 Key의 소비가 할당량을 크게 넘지 않았는지도 봐야 합니다. 두 조건을 모두 만족해야 이 세 가지 예산 라인이 비로소 실제로 사용할 수 있는 상태가 됩니다.
참고 자료
- APIYI 토큰 관리 문서: 소프트 상한, remain_quota, 일일 재설정 및 모델 화이트리스트 설명
- 링크:
docs.apiyi.com/api-capabilities/token-management
- 링크:
- APIYI 선차감 할당량 설명: 추정 선차감과 사후 정산 메커니즘
- 링크:
docs.apiyi.com/faq/pre-deduction-quota
- 링크:
- APIYI 잔액 알림 설명: 알림은 통지만 하고 차단하지 않음
- 링크:
docs.apiyi.com/faq/balance-alerts
- 링크:
- APIYI 로그 조회 문서: 증분 내보내기와 오프라인 대사
- 링크:
docs.apiyi.com/api-capabilities/log-query
- 링크:
- OWASP API Security Top 10 2023: API4 Unrestricted Resource Consumption
- 링크:
api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/
- 링크:
무릇 일은 미리 준비하면 이루어지고, 준비하지 않으면 무너진다. — 《예기·중용》
