관리
관리 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/balance | GET | Workspace 잔액 조회 |
/v1/management/api-keys | GET | API key 목록 조회 |
/v1/management/api-keys | POST | API key 생성 |
/v1/management/api-keys/{keyId} | PATCH | 이름, 한도, 모델, 만료일 또는 상태 변경 |
/v1/management/api-keys/{keyId}/usage | GET | 개별 사용량 기록 조회 |
/v1/management/api-keys/{keyId}/billing | GET | 청구 요약 조회 |
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 | 의미 |
|---|---|---|
| 400 | validation_error | 필드 또는 쿼리 파라미터가 유효하지 않음 |
| 400 | invalid_model_access | models의 모델이 Workspace의 모델 정책에서 허용되지 않음 |
| 400 | currency_retired | limitCurrency가 CNY임. USD를 사용해야 함 |
| 401 | invalid_management_token | 토큰이 없거나, 형식이 잘못되었거나, 취소됨 |
| 403 | organization_inactive | Workspace가 활성 상태가 아님 |
| 404 | not_found | API key가 이 Workspace에 존재하지 않음 |
| 409 | api_key_revoked | 취소된 키는 다시 활성화할 수 없음. 새 키를 생성해야 함 |
| 429 | report_busy | 실행 중인 사용량 또는 청구 리포트가 너무 많음. Retry-After 초 후에 다시 시도 |
예시
curl "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"