관리 API

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

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

개요

Management API 는 일반 추론용 API 키를 쓰지 않고도 조직 잔액을 조회하고, 조직 API 키를 관리하며, 특정 키의 사용량과 과금을 조회할 수 있게 해줍니다. 대시보드의 설정 페이지에서 관리 토큰을 사용하세요:

Authorization: Bearer mt-your-management-token

관리 토큰은 추론용 API 키와 다릅니다. /v1/management/* 에는 mt-... 를, /v1/responses 같은 모델 추론 엔드포인트에는 sk-... 를 사용하세요.

사용 가능한 엔드포인트

엔드포인트	메서드	설명
`/v1/management/balance`	GET	현재 조직 잔액 합계 조회
`/v1/management/api-keys`	GET	현재 조직에서 관리되는 사용자 API 키 목록 조회
`/v1/management/api-keys`	POST	새 사용자 API 키 생성
`/v1/management/api-keys/{keyId}`	PATCH	이름, 사용 한도, 허용 모델, 만료, 상태 업데이트
`/v1/management/api-keys/{keyId}/usage`	GET	특정 키의 페이지네이션된 사용 상세 조회
`/v1/management/api-keys/{keyId}/billing`	GET	특정 키의 집계 과금 내역 조회

사용 필터 계약

GET /v1/management/api-keys/{keyId}/usage 는 다음 query 파라미터를 지원합니다.

파라미터	타입	기본값 / 제한	설명
`page`	integer	기본값 `1`, 최소 `1`	1부터 시작하는 페이지 번호
`limit`	integer	기본값 `50`, 최소 `1`, 최대 `100`	페이지 크기
`model`	string	최대 길이 `100`	호출자가 요청한 공개 모델 이름
`modelVendor`	string	최대 길이 `100`	공개 모델 공급자
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	포함 시작 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 를 지원합니다
`endDate`	string	-	포함 종료 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 를 지원합니다

startDate 와 endDate 를 함께 보내는 경우 startDate 는 endDate 보다 빠르거나 같아야 합니다.

API 키 본문 계약

POST /v1/management/api-keys

필드	타입	기본값 / 제한	설명
`name`	string	필수, 기본값 `Default Key`, 길이 `1-50`	표시 이름이며 서버에서 앞뒤 공백을 제거합니다
`limitAmount`	number \| null	최소 `0`, 입력 최대 `1000000`	`null` 또는 생략 = 무제한, `0` = 0 한도. 양수는 저장된 상한으로 정규화되며 USD 환산 기준 `100000` 을 넘지 않습니다
`limitCurrency`	enum	기본값 `USD`	USD만 지원됩니다. `CNY`를 보내면 `400 currency_retired`가 반환됩니다.
`models`	string[]	기본값 `[]`	선택적 모델 허용 목록
`expiresAt`	string \| null	RFC3339 datetime	`null` 은 만료 없음 의미

PATCH /v1/management/api-keys/

필드	타입	기본값 / 제한	설명
`status`	enum	-	`active`, `inactive`, `revoked`
`name`	string	길이 `1-50`	업데이트된 표시 이름
`limitAmount`	number \| null	최소 `0`, 입력 최대 `1000000`	`null` = 무제한, `0` = 0 한도. 양수는 저장된 상한으로 정규화되며 USD 환산 기준 `100000` 을 넘지 않습니다
`limitCurrency`	enum	기본값 `USD`	USD만 지원됩니다. `CNY`를 보내면 `400 currency_retired`가 반환됩니다.
`models`	string[]	-	업데이트된 모델 허용 목록
`expiresAt`	string \| null	RFC3339 datetime	`null` 은 만료 제거

PATCH 요청에는 최소 1개 이상의 필드가 포함되어야 합니다.

금액 필드

Management API의 금액 요청 및 응답 필드는 USD만 지원합니다.
limitCurrency의 기본값은 USD입니다. CNY를 보내면 400 currency_retired가 반환됩니다.

리포팅 의미

model 은 호출자가 요청한 공개 모델을 의미합니다.
modelVendor 는 숨겨진 호환 경로가 아니라 공개 모델 공급자를 의미합니다.
scene 은 엔드포인트 또는 작업 유형에서 파생된 공개 요청 장면입니다.

응답에는 공개 가능한 과금 및 리포팅 필드만 포함되며, 내부 라우팅 세부 정보와 물리 공급자 메타데이터는 숨겨집니다.

/usage 개별 항목은 기본 요청의 정산이 완료되면 billing_transaction_id 를 포함할 수 있습니다. 요청 단위 대조에는 request_id 와 billing_transaction_id 를 함께 사용하세요.

청구 페이지네이션 참고

/usage 는 페이지네이션됩니다. /billing 은 현재 집계형 엔드포인트이므로 page / limit 형태의 페이지네이션 메타데이터를 반환하지 않습니다. 행 단위 상세 기록이 필요하다면 /usage 를 사용하세요.

빠른 예시

먼저 현재 관리 토큰으로 조직 잔액을 확인하세요.

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

이어서 같은 관리 토큰으로 조회 가능한 API 키 목록을 확인하세요.

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

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

핵심

텍스트

파일 및 배치

이미지

오디오 및 실시간

음악

비디오 및 자료

Worlds

3D

비동기 작업

Gemini 네이티브

관리

개요

사용 가능한 엔드포인트

사용 필터 계약

API 키 본문 계약

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

금액 필드

리포팅 의미

청구 페이지네이션 참고

빠른 예시

다음 단계

​개요

​사용 가능한 엔드포인트

​사용 필터 계약

​API 키 본문 계약

​POST /v1/management/api-keys

​PATCH /v1/management/api-keys/

​금액 필드

​리포팅 의미

​청구 페이지네이션 참고

​빠른 예시

​다음 단계

개요

사용 가능한 엔드포인트

사용 필터 계약

API 키 본문 계약

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

금액 필드

리포팅 의미

청구 페이지네이션 참고

빠른 예시

다음 단계