TokenLab

관리

관리 API

Workspace 잔액 확인, API key 관리, 사용량 및 청구 내역 조회

자체 백엔드나 자동화 환경에서 Management API를 사용하여 TokenLab Workspace를 관리할 수 있습니다. 관리 토큰(management token)을 사용하므로 프로그램에 일반 API key가 필요하지 않습니다.

대시보드 → API → Management Tokens에서 관리 토큰을 생성하세요:

Authorization: Bearer mt-your-management-token

관리 토큰과 API key는 역할이 다릅니다. mt-...는 /v1/management/*에만 사용하세요. /v1/responses와 같은 모델 API에는 sk-...를 사용하세요.

엔드포인트

엔드포인트메서드용도
/v1/management/balanceGETWorkspace 잔액 조회
/v1/management/api-keysGETAPI key 목록 조회
/v1/management/api-keysPOSTAPI key 생성
/v1/management/api-keys/{keyId}PATCH이름, 한도, 모델, 만료일 또는 상태 변경
/v1/management/api-keys/{keyId}/usageGET개별 사용량 기록 조회
/v1/management/api-keys/{keyId}/billingGET청구 요약 조회

API Keys

  • 새 키의 전체 시크릿은 생성 응답에서만 확인할 수 있습니다.
  • models: []는 키 수준의 모델 제한을 두지 않습니다.
  • limitAmount: null은 무제한을 의미합니다. 0은 해당 키로 비용이 발생하는 것을 방지합니다.
  • 금액은 USD를 사용합니다. CNY를 전달하면 400 currency_retired가 반환됩니다.
  • inactive 상태는 다시 활성화할 수 있습니다. 키를 영구적으로 폐기하려면 revoked를 사용하세요.

사용량 및 청구

/usage는 페이지네이션된 기록을 반환하며 모델, 모델 제공사(maker), 씬(scene) 및 날짜 필터를 지원합니다. 정산된 기록에는 billing_transaction_id가 포함될 수 있습니다. 청구 내역과 요청을 매칭해야 할 때 이를 request_id와 함께 저장하세요.

/billing은 모델, 모델 제공사, 씬, 날짜별로 그룹화된 합계를 반환합니다. Workspace 충전이나 인보이스는 포함되지 않습니다.

2026-07-31과 같이 날짜만 지정된 endDate는 해당 일자의 시작 시점인 00:00 UTC를 의미합니다. 하루 전체를 포함하려면 다음 날짜나 2026-07-31T23:59:59Z와 같은 RFC3339 시간 형식을 전달하세요.

오류

오류는 표준 error 객체를 사용합니다. 상태 코드와 code를 통해 처리하세요.

상태code의미
400validation_error필드 또는 쿼리 파라미터가 유효하지 않음
400invalid_model_accessmodels의 모델이 Workspace의 모델 정책에서 허용되지 않음
400currency_retiredlimitCurrency가 CNY임. USD를 사용해야 함
401invalid_management_token토큰이 없거나, 형식이 잘못되었거나, 취소됨
403organization_inactiveWorkspace가 활성 상태가 아님
404not_foundAPI key가 이 Workspace에 존재하지 않음
409api_key_revoked취소된 키는 다시 활성화할 수 없음. 새 키를 생성해야 함
429report_busy실행 중인 사용량 또는 청구 리포트가 너무 많음. Retry-After 초 후에 다시 시도

예시

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

다음 단계

이 페이지의 내용