API 문서 · 시작하기

Key 권한 및 한도

scope, 모델 허용 목록, 누적 및 일일 한도, 비활성화와 폐기.

한 계정에서 여러 개의 Key를 만들 수 있습니다. 한도 설정과 폐기를 독립적으로 관리할 수 있도록 애플리케이션이나 환경마다 별도의 Key를 쓰는 것을 권장합니다.

권한(scope)

scope	허용되는 작업
`tasks:create`	영상 생성 작업 제출(한도 예치 및 정산 발생)
`tasks:read`	이 계정의 작업 상태와 결과 조회
`assets:read`	에셋 목록 및 상세 보기
`assets:write`	에셋 업로드, 가져오기, 이름 변경, 삭제

모델 허용 목록

Key는 생성 시 선택한 모델만 호출할 수 있으며, 해당 모델은 계정에 권한이 부여된 모델이어야 합니다. 플랫폼에 새로 추가된 모델은 기존 Key의 허용 목록에 자동으로 추가되지 않습니다.

한도

누적 한도(필수): 해당 Key의 정산 완료 금액과 예치 중인 금액의 합이 이 값을 넘을 수 없습니다.
일일 한도(선택): 이 사이트의 시간대(Asia/Shanghai) 기준 하루 단위로 계산합니다.
RPM 및 동시 실행 한도(선택): 초과하면 429 rate_limited를 반환합니다. 속도 제한을 참고하세요.
유효 기간(선택): 만료 후 요청은 401 invalid_api_key를 반환합니다.

Key 한도가 부족하면 402 key_limit_exceeded, 계정의 사용 가능 한도가 부족하면 402 quota_exceeded를 반환합니다.

비활성화와 폐기

비활성화한 Key는 언제든 다시 활성화할 수 있지만, 폐기한 Key는 복구할 수 없습니다. 두 경우 모두 해당 Key를 쓰는 요청은 즉시 401을 반환하며, 과거 작업과 청구 내역은 그대로 보존됩니다.

cURL

curl https://cn-api.aitoken.tools/v1/account/quota \
  -H "Authorization: Bearer $AITOKEN_API_KEY"

# {
#   "object": "quota",
#   "currency": "CNY",
#   "available": "496.800000",
#   "reserved": "3.200000",
#   "key": { "id": "key_xxx", "total_remaining": "96.800000", "daily_remaining": null }
# }