TokenLab Management API, 워크스페이스 잔액 조회 기능 추가

잔액 부족으로 인해 자동화된 프로덕션 파이프라인이 중단되는 문제는 사전에 방지할 수 있습니다. TokenLab Management API 잔액 조회 기능을 사용하면 추론 키 대신 관리 토큰을 활용하여 자동화된 워크플로에서 잔액 총액을 쿼리할 수 있습니다.

이 가이드에서는 GET /v1/management/balance 엔드포인트 규약, 인증 요구 사항, 통화 처리 방식, 공식 문서를 통해 응답 스키마를 직접 검증하는 방법을 다룹니다.

핵심 요약

• Management API 잔액 엔드포인트(GET /v1/management/balance)는 현재 워크스페이스 잔액, 총 충전액, 누적 사용 금액을 반환합니다.
• 인증에는 Dashboard → API → Management Tokens에서 생성된 관리 토큰(mt-...)이 필요하므로, 운영상의 확인 작업을 모델 추론 키(sk-...)와 분리하여 유지할 수 있습니다.
• 모든 통화 값은 USD 단위로 반환됩니다. 정확한 계산을 위해서는 반환된 십진수 문자열(balance_decimal, total_recharge_decimal, total_used_decimal)을 사용해야 합니다.
• 이 엔드포인트는 /v1/management/api-keys/{keyId}/usage 및 /v1/management/api-keys/{keyId}/billing과 같은 키 수준의 리포팅과 연계하여 사용할 수 있습니다.

관리 토큰 vs. 모델 추론 API 키

관리 토큰과 모델 추론 키는 TokenLab에서 서로 다른 운영 역할을 수행합니다.

• 모델 추론 API 키 (sk-...): POST /v1/chat/completions, POST /v1/responses, POST /v1/messages의 네이티브 Anthropic Messages, /v1beta/models/...의 Gemini와 같은 추론 엔드포인트를 호출하는 데 사용됩니다. 이 키들은 생성 요청을 실행하지만 조직 수준의 재무 데이터를 노출하지는 않습니다.
• 관리 토큰 (mt-...): /v1/management/* 경로로 제한됩니다. 백엔드가 모델 생성 권한을 얻지 않고도 워크스페이스 잔액을 검사하고, API 키를 나열 또는 편집하며, 사용량을 모니터링할 수 있도록 지원합니다.

이러한 자격 증명을 분리하면 회계 스크립트와 재무 모니터링 시스템이 과금 가능한 추론 호출을 유발하지 않도록 보장하는 동시에, 모델 워커가 계정 관리 권한에 접근하지 못하도록 방지할 수 있습니다.

잔액 엔드포인트 통신 규약

Authorization 헤더에 관리 토큰을 포함하여 https://api.tokenlab.sh/v1/management/balance로 GET 요청을 전송합니다.

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

응답 스키마

성공적인 요청은 organization_balance 객체와 함께 200 OK를 반환합니다.

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

응답 필드

• object (string): 항상 organization_balance입니다.
• organization_id (string): 현재 관리 토큰과 연결된 조직입니다.
• balance (number): 표시용 부동소수점 숫자로 나타낸 USD 단위의 현재 워크스페이스 잔액입니다.
• balance_decimal (string): 재무 정산을 위해 십진수 문자열로 포맷된 USD 단위의 정확한 현재 워크스페이스 잔액입니다.
• total_recharge (number): USD 단위의 총 성공적인 워크스페이스 충전 금액입니다.
• total_recharge_decimal (string): 십진수 문자열로 포맷된 USD 단위의 정확한 총 성공적인 워크스페이스 충전 금액입니다.
• total_used (number): USD 단위의 총 워크스페이스 사용 비용입니다.
• total_used_decimal (string): 십진수 문자열로 포맷된 USD 단위의 정확한 총 워크스페이스 사용 비용입니다.

통화 필드는 엄격히 USD 기준입니다. 임계값 확인이나 원장 대사를 위해 잔액을 프로그래밍 방식으로 파싱할 때는 정밀도 손실을 방지하기 위해 부동소수점 기본 타입 대신 임의 정밀도 십진수 라이브러리를 사용하여 balance_decimal을 파싱하세요.

잔액 확인 구현

일반적인 연동 패턴은 다음과 같습니다.

1. 배치 사전 가드레일(Pre-Batch Guardrails): gpt-5.5 또는 glm-5.2와 같은 모델에서 대규모 생성 작업 등 큰 워크로드를 전달하기 전에 /v1/management/balance를 쿼리합니다. 만약 balance_decimal이 예상 배치 비용보다 낮아지면 작업 큐를 일시 중지합니다.
2. 잔액 부족 알림: 자동 이메일 알림은 Console → Settings에서 구성할 수 있지만, 예약된 모니터링 크론(cron)을 통해 엔드포인트를 폴링하고 내부 Slack, PagerDuty 또는 웹훅 알림을 트리거할 수도 있습니다.
3. 청구 내역 정산: 실시간 워크스페이스 잔액과 개별 키 사용 기록(/v1/management/api-keys/{keyId}/usage)을 결합하여 확정된 인보이스 항목과 토큰 지출액을 대사합니다.

전체 엔드포인트 사양 및 키 관리 방법은 워크스페이스 잔액 조회 API 레퍼런스 및 Management API 개요를 참조하세요.