잔액 조회 API

API 개요

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

인증 토큰을 받는 방법

콘솔 액세스

api.apiyi.com/account/profile를 방문하여 프로필 페이지에 액세스합니다

시스템 토큰 찾기

페이지 하단의 “Account Options - System Token” 섹션을 찾습니다

액세스 토큰 생성

계정 비밀번호를 입력하면 이후 API 쿼리에 사용할 수 있는 액세스 토큰을 받을 수 있습니다

API 정보

항목	설명
API URL	`https://api.apiyi.com/api/user/self`
Method	`GET`
Authentication	Authorization 헤더
Response Format	JSON

요청 세부 정보

요청 헤더

헤더 이름	필수	설명
`Authorization`	예	API 액세스 토큰, 형식: 직접 토큰 문자열
`Accept`	아니요	권장: `application/json`
`Content-Type`	아니요	권장: `application/json`

요청 매개변수

이것은 GET 요청이며 요청 본문 매개변수는 필요하지 않습니다.

응답 세부정보

성공 응답 예시

{
  "success": true,
  "message": null,
  "data": {
    "id": 19489,
    "username": "testnano",
    "display_name": "testnano",
    "role": 1,
    "status": 1,
    "email": "",
    "quota": 24997909,
    "used_quota": 10027091,
    "request_count": 339,
    "group": "ceshi",
    "aff_code": "ZM0H",
    "inviter_id": 0,
    "access_token": "...",
    "ModelFixedPrice": [...]
  }
}

주요 응답 필드

Field Name	Type	Description
`success`	불리언	요청이 성공했는지 여부
`message`	문자열	오류 메시지 (성공 시 null)
`data.username`	문자열	사용자 이름
`data.display_name`	문자열	표시 이름
`data.quota`	정수	남은 쿼터 (현재 사용 가능한 잔액, 쿼터 단위)
`data.used_quota`	정수	사용한 쿼터 (쿼터 단위)
`data.request_count`	정수	총 요청 수
`data.group`	문자열	사용자 그룹
`data.ModelFixedPrice`	배열	모델 요금 목록 (무시해도 됨)

쿼터 변환

변환 규칙

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 - 인증 실패

{
  "success": false,
  "message": "Unauthorized"
}

Reason: Authorization token이 유효하지 않거나 만료되었습니다 Solution: API token을 확인하고 업데이트하십시오

HTTP 403 - 권한 거부

{
  "success": false,
  "message": "Forbidden"
}

Reason: 현재 token에는 이 API에 접근할 권한이 없습니다 Solution: 관리자에게 문의하여 권한 설정을 확인하십시오

코드 예시

cURL 예제

curl --compressed 'https://api.apiyi.com/api/user/self' \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json'

중요: API가 gzip으로 압축된 콘텐츠를 반환하므로 --compressed 옵션이 필요합니다. 그렇지 않으면 깨진 출력이 표시됩니다.

빠른 테스트(YOUR_TOKEN_HERE를 바꾸십시오):

export APIYI_TOKEN='YOUR_TOKEN_HERE'

curl --compressed -s 'https://api.apiyi.com/api/user/self' \
  -H 'Accept: application/json' \
  -H "Authorization: $APIYI_TOKEN" \
  -H 'Content-Type: application/json' | \
  jq '.data | {quota, used_quota, request_count}'

참고: -s 옵션은 진행률 표시줄을 숨기고, --compressed은 gzip 응답을 자동으로 압축 해제합니다.

Python 예제 (기본)

import requests

{/* Configuration */}
url = "https://api.apiyi.com/api/user/self"
authorization = "YOUR_TOKEN_HERE"  # Replace with your token

{/* Request headers */}
headers = {
    'Accept': 'application/json',
    'Authorization': authorization,
    'Content-Type': 'application/json'
}

{/* Send request */}
response = requests.get(url, headers=headers, timeout=10)

{/* Check response */}
if response.status_code == 200:
    data = response.json()
    user_data = data['data']

    {/* Extract key information */}
    quota = user_data['quota']
    used_quota = user_data['used_quota']
    request_count = user_data['request_count']

    {/* Calculate USD amounts */}
    {/* Note: quota represents current remaining balance */}
    remaining_usd = quota / 500000
    used_usd = used_quota / 500000

    {/* Print results */}
    print(f"Remaining quota: ${remaining_usd:.2f} USD ({quota:,} quota)")
    print(f"Used: ${used_usd:.2f} USD ({used_quota:,} quota)")
    print(f"Request count: {request_count:,} times")
else:
    print(f"Request failed: HTTP {response.status_code}")
    print(response.text)

Python 예제 (최적화)

다음 기능을 갖춘 완전한 최적화 스크립트 quota_optimized.py를 제공합니다.

오류 처리

완전한 예외 처리와 오류 캡처

환경 변수

안전한 token 관리, 하드코딩 방지

서식화된 출력

보기 좋은 표 표시와 숫자 서식 지정

자동 변환

USD 금액 자동 계산

사용법:

{/* Method 1: Using environment variable (recommended) */}
export APIYI_TOKEN='YOUR_TOKEN_HERE'
python quota_optimized.py

{/* Method 2: Command line argument */}
python quota_optimized.py 'YOUR_TOKEN_HERE'

출력 예시:

============================================================
📊 APIYI Account Balance Information
============================================================
Username: testnano (testnano)
------------------------------------------------------------
Remaining quota: 24,997,909 quota ($49.99 USD)
Used:           10,027,091 quota ($20.05 USD)
Request count: 339 times
============================================================
💡 Conversion: 500,000 quota = $1.00 USD
============================================================

자주 묻는 질문

Authorization token은 어떻게 얻습니까?

위의 “Authorization Token을 얻는 방법” 섹션을 참조하거나, 콘솔의 프로필 페이지를 방문하여 시스템 token을 얻으십시오.

잔액 조회 시 quota가 소모됩니까?

아니요, 잔액 조회 API는 quota를 소모하지 않습니다.

잔액은 얼마나 자주 조회할 수 있습니까?

요청 제한을 유발하지 않도록 조회 간격은 최소 1초를 권장합니다.

ModelFixedPrice 필드는 무엇을 위한 것입니까?

이 필드는 다양한 AI 모델의 요금 정보를 반환합니다. 잔액 정보만 필요하다면 무시해도 됩니다.

quota 필드는 무엇을 나타냅니까?

quota 필드는 현재 남은 잔액을 나타냅니다. quota이 0이거나 0에 가까우면 계정 잔액이 부족하여 충전이 필요합니다.

curl이 깨진 텍스트를 반환하거나 jq가 오류를 보고하는 이유는 무엇입니까?

문제: curl을 실행하면 깨진 텍스트가 반환되거나 jq가 “Invalid numeric literal” 오류를 보고합니다이유: API는 gzip 압축 콘텐츠(Content-Encoding: gzip)를 반환하며, curl은 이를 자동으로 압축 해제하지 않습니다.해결 방법: curl이 자동으로 압축 해제하도록 --compressed 옵션을 추가합니다:

{/* ✅ Correct (with --compressed) */}
curl --compressed 'https://api.apiyi.com/api/user/self' \
  -H 'Authorization: YOUR_TOKEN' | jq

{/* ❌ Wrong (missing --compressed) */}
curl 'https://api.apiyi.com/api/user/self' \
  -H 'Authorization: YOUR_TOKEN' | jq

중요 참고 사항

보안 유의 사항

코드에 Authorization token을 하드코딩하지 마십시오
민감한 정보를 관리할 때는 환경 변수 또는 설정 파일을 사용하십시오
token이 포함된 코드를 공개 저장소에 커밋하지 마십시오

요청 제한

적절한 요청 timeout을 설정하십시오(권장: 10초)
지나치게 빈번한 쿼리 요청을 피하십시오

예외 처리 권장 사항

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

응답 형식 참고 사항

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

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 API

API 개요

인증 토큰을 받는 방법

API 정보

요청 세부 정보

요청 헤더

요청 매개변수

응답 세부정보

성공 응답 예시

주요 응답 필드

쿼터 변환

변환 규칙

오류 응답

HTTP 401 - 인증 실패

HTTP 403 - 권한 거부

코드 예시

cURL 예제

Python 예제 (기본)

Python 예제 (최적화)

오류 처리

환경 변수

서식화된 출력

자동 변환

자주 묻는 질문

중요 참고 사항

예외 처리 권장 사항

응답 형식 참고 사항

​API 개요

​인증 토큰을 받는 방법

​API 정보

​요청 세부 정보

​요청 헤더

​요청 매개변수

​응답 세부정보

​성공 응답 예시

​주요 응답 필드

​쿼터 변환

변환 규칙

​오류 응답

​HTTP 401 - 인증 실패

​HTTP 403 - 권한 거부

​코드 예시

​cURL 예제

​Python 예제 (기본)

​Python 예제 (최적화)

오류 처리

환경 변수

서식화된 출력

자동 변환

​자주 묻는 질문

​중요 참고 사항

예외 처리 권장 사항

응답 형식 참고 사항

API 개요

인증 토큰을 받는 방법

API 정보

요청 세부 정보

요청 헤더

요청 매개변수

응답 세부정보

성공 응답 예시

주요 응답 필드

쿼터 변환

오류 응답

HTTP 401 - 인증 실패

HTTP 403 - 권한 거부

코드 예시

cURL 예제

Python 예제 (기본)

Python 예제 (최적화)

자주 묻는 질문

중요 참고 사항