메인 콘텐츠로 건너뛰기

API 개요

Balance Query API는 총 쿼터, 사용한 쿼터, 남은 잔액, 요청 수를 포함하여 계정의 현재 쿼터 사용 현황을 가져옵니다. 이 API를 사용하면 계정 잔액을 쉽게 모니터링할 수 있어, 선제적이고 유연한 잔액 알림 관리가 가능합니다.

Authorization Token 발급 방법

이 API는 개인 액세스 token(nap_로 시작)으로 인증합니다. 모델 호출에 사용하는 API Key와는 다릅니다.
1

개인 액세스 Tokens 열기

api.apiyi.com/account/profile의 프로필 페이지로 이동합니다. 계정 옵션에서 개인 액세스 Tokens → Token 생성을 클릭합니다.
2

권한 선택

이 API에는 Profile · Read 권한만 필요합니다. 기본 유효 기간은 30일이므로 더 긴 기간을 선택하는 것을 권장합니다.
3

token 저장

token이 생성된 직후 복사하여 Authorization 헤더에 설정합니다.
개인 액세스 token 생성: 이름, 유효 기간, IP 허용 목록 및 권한
기존 시스템 tokens는 2026-11-11 (UTC+8)에 폐기될 예정입니다. “계정 옵션 - 시스템 Token”에서 생성된 AccessTokens는 그때까지 계속 작동합니다. 해당 날짜 이후에는 401 ACCESS_TOKEN_LEGACY_RETIRED을 반환합니다. 사용량을 검토하여 일정을 연장할 수도 있지만, 지금 개인 액세스 token으로 전환하는 것을 권장합니다. 헤더 값만 교체하면 되며, 기존 코드는 그대로 유지됩니다. 유효 기간, IP 허용 목록 및 권한에 대한 자세한 내용은 개인 액세스 token이란 무엇인가요?를 참고하시기 바랍니다.

API 정보

요청 상세 정보

요청 헤더

요청 파라미터

이 요청은 GET 요청이며 요청 본문 파라미터가 필요하지 않습니다.

응답 세부정보

성공 응답 예시

주요 응답 필드

쿼터 변환

변환 규칙

500,000 quota = $1.00 USD
계산 공식:
  • USD 금액 = quota ÷ 500,000
  • 남은 쿼터 = quota (quota는 현재 남은 잔액을 나타냄)
  • 남은 USD = quota ÷ 500,000
예시:
  • quota: 24997909 → $49.99 USD (현재 남은 잔액)
  • used_quota: 10027091 → $20.05 USD (사용한 금액)

오류 응답

HTTP 401 - 인증 실패

원인: token이 유효하지 않거나 만료되었거나 삭제되었습니다. 계정 비밀번호, 2단계 인증 또는 패스키를 변경하면 모든 개인 액세스 token이 무효화됩니다. 해결 방법: 콘솔에서 새 개인 액세스 token을 생성하십시오. 다른 두 가지 401 응답에는 명시적인 메시지가 포함됩니다:

HTTP 403 - 권한 거부

원인: 개인 액세스 token에 Profile · Read 권한이 없습니다. 해결 방법: 해당 권한을 가진 새 token을 생성하십시오. 권한은 생성 후 변경할 수 없습니다.

코드 예제

cURL 예제

중요: API가 gzip으로 압축된 콘텐츠를 반환하므로 --compressed 옵션이 필수적이며, 그렇지 않으면 출력이 깨져서 표시됩니다.
빠른 테스트 (YOUR_TOKEN_HERE를 교체하십시오):
참고: -s 옵션은 진행률 표시줄을 숨기며, --compressed 옵션은 gzip 응답의 압축을 자동으로 해제합니다.

Python 예제 (기본)

Python 예제 (최적화)

기본 예제에 다음 사항이 추가되었습니다:

오류 처리

완전한 예외 처리 및 오류 포착

환경 변수

안전한 토큰 관리 및 하드코딩 방지

서식화된 출력

깔끔한 표 표시 및 숫자 서식 지정

자동 변환

USD 금액 자동 계산
아래 코드를 quota.py 파일로 저장하면 바로 실행할 수 있습니다:
사용 방법:
출력 예시:

자주 묻는 질문

상단의 “Authorization token 발급 방법” 단계를 따르십시오. 프로필 페이지에서 개인 액세스 token을 생성하고 “Profile · Read”를 선택하십시오. 기존 레거시 시스템 token은 2026-11-11 (UTC+8)에 폐기될 예정입니다. 개인 액세스 token이란 무엇입니까?를 참조하십시오.
아니요, 잔액 조회 API는 쿼터를 소모하지 않습니다.
요청 제한이 발생하지 않도록 최소 1초 이상의 조회 간격을 유지하는 것을 권장합니다.
이 필드는 다양한 AI 모델의 가격 정보를 반환합니다. 잔액 정보만 필요한 경우에는 무시하셔도 됩니다.
quota 필드는 현재 남은 잔액을 나타냅니다. quota이 0이거나 0에 가까우면 계정 잔액이 부족한 상태이므로 충전이 필요합니다.
문제: curl 실행 시 문자가 깨져 출력되거나 jq에서 “Invalid numeric literal” 오류가 발생합니다.원인: API가 gzip으로 압축된 콘텐츠(Content-Encoding: gzip)를 반환하지만 curl이 이를 자동으로 압축 해제하지 않기 때문입니다.해결 방법: curl이 자동으로 압축을 해제하도록 --compressed 옵션을 추가하십시오:

중요 참고 사항

보안 유의 사항
  • 코드에 Authorization token을 하드코딩하지 마십시오
  • 민감한 정보를 관리할 때는 환경 변수 또는 설정 파일을 사용하십시오
  • token이 포함된 코드를 공개 저장소에 커밋하지 마십시오
요청 제한
  • 적절한 요청 timeout을 설정하십시오(권장: 10초)
  • 지나치게 빈번한 쿼리 요청을 피하십시오

예외 처리 권장 사항

  • 네트워크 예외, timeout, 인증 실패를 항상 처리하십시오
  • 문제 해결을 쉽게 하기 위해 오류를 로그에 남기십시오

응답 형식 참고 사항

  • API는 gzip으로 압축된 콘텐츠를 반환합니다. curl은 --compressed 옵션이 필요합니다
  • Python의 requests 라이브러리는 추가 설정 없이 gzip 압축 해제를 자동으로 처리합니다