결제 Public API

자체 결제 도구에서 계정 잔액, 모델 사용량, 모델 비용을 조회합니다

결제 Public API는 스크립트, 대시보드, 재무 시스템에서 Atlas Cloud 결제 데이터를 읽기 위한 API입니다.

Base URL: https://api.atlascloud.ai/public/v1

엔드포인트

Endpoint	설명
`GET /balance`	현재 계정 잔액과 크레딧 요약
`GET /model-usage`	UTC 일 단위 모델 사용량
`GET /model-costs`	UTC 일 단위 모델 비용

자세한 요청과 응답 스키마는 API 레퍼런스를 확인하세요:

인증

Atlas Cloud API Key를 Authorization header에 전달합니다:

Authorization: Bearer apikey-...

API Key는 API Keys에서 만들 수 있습니다. secret key는 apikey-로 시작합니다.

일부 응답과 필터는 ak_... 형식의 API Key public ID를 사용합니다. 이 ID는 결제 리포트에 표시할 수 있지만 인증 자격 증명은 아닙니다.

권한

/model-usage와 /model-costs는 기본적으로 scope=self를 사용하며 인증된 사용자에게 귀속된 사용량을 반환합니다. 여기에는 해당 사용자가 소유한 API Key도 포함됩니다.

scope=account를 사용하면 계정 전체 사용량과 비용을 조회할 수 있습니다. 이 범위에는 account-level model billing read permission이 필요합니다. /balance는 항상 account scope이며 account balance read permission이 필요합니다.

개인 계정 owner는 자신의 계정 결제 데이터를 읽을 수 있습니다. 팀 계정에서는 Account Admin 또는 Finance 역할을 사용하세요.

잔액 조회

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

금액은 소수점 6자리 문자열과 currency로 반환됩니다:

{
  "value": "125.500000",
  "currency": "usd"
}

사용량 및 비용 쿼리 파라미터

start_date와 end_date는 필수 UTC 날짜이며 형식은 YYYY-MM-DD입니다. end_date는 exclusive이고 최대 범위는 180일입니다.

/model-usage와 /model-costs의 공통 쿼리 파라미터입니다. group_by[]를 생략하면 일별 합계를 반환합니다:

파라미터	설명
`start_date`	`YYYY-MM-DD` 형식의 포함 UTC 시작일
`end_date`	`YYYY-MM-DD` 형식의 제외 UTC 종료일. 범위는 최대 180일입니다
`scope`	`self` 또는 `account`; 기본값 `self`
`group_by[]`	선택적 그룹화. 지원 조합: `model_type`, `model`, `api_key`, 또는 `model`과 `api_key`; 모델별 내역은 `group_by[]=model`을 사용하세요
`model_types[]`	`text`, `image`, `video` 반복 지정
`model_ids[]`	모델 ID 필터; 최대 100개
`api_key_ids[]`	`ak_...` API Key public ID 필터; 최대 100개
`limit`	페이지당 행 수, 1~1000; 기본값 100
`page`	`next_page`에서 받은 불투명 cursor

배열 파라미터는 반복 파라미터 형식으로 보내야 합니다. 쉼표로 구분한 값은 거부됩니다.

사용량 조회

기본 응답은 일별 사용량 합계를 반환합니다.

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

비용 조회

/model-costs는 /model-usage와 동일한 날짜 범위, scope, 필터, 그룹화, 페이지네이션 파라미터를 사용합니다. group_by[]를 생략하면 일별 비용 합계를 반환합니다.

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

페이지네이션

has_more가 true이면 next_page 값을 그대로 page 쿼리 파라미터로 전달합니다. cursor는 불투명 값으로 취급하고 다른 쿼리 파라미터는 변경하지 마세요.

오류와 제한

오류는 안정적인 envelope를 사용합니다:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

레이트 리밋 응답은 429 rate_limit_error를 반환하며 Retry-After header를 포함할 수 있습니다.

목차