GET
/balance유닛 잔액 조회
보유 유닛과 초과 사용량, 현재 차단 상태 조회
관리 API 키가 연결된 스페이스의 잔액 조회 방법과 unit 단위 수량, 초과 사용 허용 여부, 차단 상태를 설명합니다.
페이지 목차
요청 준비하기
관리 API 키가 연결된 스페이스의 현재 잔액을 조회합니다. 특정 월의 요청 수와 USD 비용이 필요하면 월별 사용량 조회를 사용합니다.
- 요청 주소:
https://openapi.letsur.ai/v1아래의 엔드포인트입니다. - 인증: 요청의
Authorization헤더에 관리 API 키를 넣습니다. AI 게이트웨이 API 키로는 호출할 수 없습니다. 키는 관리 API 키 준비와 보관 방법에 따라 준비합니다. - 클라이언트 생성용 JSON: OpenAPI 스키마 가져오기에서 받습니다.
OpenAPI v2026.11.20, 공개 문서 기준문서용 JSON 열기
요청 파라미터
별도 쿼리 또는 경로 파라미터가 없습니다.
응답
200성공 응답
heldobject필수현재 사용할 수 있는 유닛입니다.
promostring필수프로모션으로 지급된 유닛입니다.
패턴^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$paidstring필수구매한 유닛입니다.
패턴^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$totalstring필수현재 사용할 수 있는 전체 유닛입니다.
패턴^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
overageobject필수초과 사용량과 초과 사용 허용 여부입니다.
accruedstring필수누적된 초과 사용량입니다. 단위는 unit입니다.
패턴^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$allowedboolean필수초과 사용 허용 여부입니다.
blockedboolean필수현재 사용 차단 여부입니다.
422요청 검증 오류
detailarray<object>요청 검증에 실패한 항목 목록입니다.
locarray<string | integer>필수오류가 발생한 요청 위치입니다.
msgstring필수오류 설명입니다.
typestring필수오류 유형입니다.
잔액과 초과 사용 읽기
HTTP 200 응답을 읽을 때는 다음 규칙을 따릅니다. 각 필드의 뜻은 위 응답에 있습니다.
- 수량 필드는 unit 수를 문자열로 담습니다. KRW 청구액이 아닙니다.
overage.accrued필드에 초과 사용량이 기록됐다고 해서 이후에도 초과 사용이 허용되는 것은 아닙니다. 허용 여부는overage.allowed필드로 판단합니다.blocked필드는 보유 유닛 수량(held)과 함께 봅니다.
차단 상태와 잔액을 확인한 뒤 구매 등 다음 작업을 정하려면 유닛 잔액과 호출 가능 상태를 확인합니다.
오류와 복구
조회가 실패했을 때는 잔액을 0으로 저장하지 말고 HTTP 상태와 오류 내용을 확인하세요.
422를 받으면 응답detail배열의 각 항목에서loc와msg로 검증에 실패한 위치와 이유를 확인합니다.- 인증에 실패했다면 관리 API 인증의 확인 항목에 따라 요청 주소와 관리 API 키, Bearer 헤더를 확인합니다. 최근 관리 API 키를 재발급했다면 이전 키는 즉시 무효화되므로 연동에 새 키가 설정됐는지 확인합니다.