TokenLab

시작하기

인증

API 키를 사용하여 TokenLab API 요청 인증하기

API 키

모델 호출 및 비공개 리소스에는 API 키가 필요합니다. GET /v1/models 및 GET /v1/models/{model}과 같은 공개 검색 엔드포인트는 키 없이도 작동합니다. 성공적인 검색 응답이 키가 정상적으로 작동함을 보장하지는 않으므로, Quickstart를 따라 모델 요청을 보내보시기 바랍니다. 저장된 전체 키를 사용하십시오. 키 목록에 표시된 접두사로는 인증할 수 없습니다.

OpenAI 호환 엔드포인트의 경우 다음과 같이 전송하십시오:

Authorization: Bearer sk-your-api-key

Anthropic 호환 /v1/messages 요청의 경우 다음을 사용할 수도 있습니다:

x-api-key: sk-your-api-key

Gemini 호환 /v1beta/* 요청 또한 x-goog-api-key: sk-your-api-key를 허용합니다. URL은 로그에 남는 경우가 많으므로 ?key= 쿼리 매개변수보다는 헤더를 사용하는 것을 권장합니다.

관리 토큰 (Management Tokens)

관리 API 엔드포인트는 별도의 토큰 유형을 사용합니다:

Authorization: Bearer mt-your-management-token

관리 토큰은 /v1/management/* 엔드포인트에서만 사용하십시오. API → Tokens를 열어 선택한 워크스페이스에 대한 토큰을 생성하거나 교체할 수 있습니다. 토큰이 표시될 때 전체 토큰을 저장하십시오. 생성 또는 교체 후 한 번만 표시됩니다.

관리 토큰은 모델 추론에 사용할 수 없으며, 표준 sk-... API 키는 관리 API에 사용할 수 없습니다.

API 키 발급받기

  1. TokenLab Console에 로그인합니다.
  2. API Keys를 엽니다.
  3. 새 키를 생성합니다.
  4. 식별 가능한 이름을 지정합니다.
  5. 한 번만 표시되므로 즉시 복사해 두십시오.
  • 클라이언트 측 코드에 API 키를 노출하지 마십시오.
  • 버전 관리 시스템에 API 키를 커밋하지 마십시오.
  • 환경 변수나 보안 관리자(secret manager)를 사용하십시오.
  • 주기적으로 키를 교체하십시오.
  • 사용하지 않는 키는 삭제하십시오.

API 키 사용하기

환경 변수 설정 및 첫 번째 전체 요청은 빠른 시작를 참조하십시오. 선택한 API 형식에 맞는 SDK를 사용하고, 키는 서버 측에 보관하십시오.

키 설정

각 API 키에 대한 설정은 Console 또는 관리 API를 통해 수행할 수 있습니다:

설정설명
지출 한도 (Spending limit)No limit은 워크스페이스 잔액을 사용합니다. Fixed limit은 설정된 금액에 도달하면 402 quota_exceeded를 반환합니다.
허용된 모델 (Allowed models)해당 키로 호출 가능한 모델을 제한합니다. 다른 모델 호출 시 403 model_not_allowed가 반환됩니다. 비워두면 키 수준의 제한이 없습니다.
전송 옵션 (Delivery option)해당 키를 통한 요청에 대해 Auto, Verified, Official을 설정합니다. 비워두면 워크스페이스 기본값이 적용됩니다. 결제 및 가격 책정을 참조하십시오.
만료 (Expiration)설정된 시간이 지나면 키는 401 expired_api_key를 반환합니다.
상태 (Status)inactive(일시 중지) 상태의 키는 401 invalid_api_key를 반환합니다. revoked(취소)된 키는 다시 활성화할 수 없습니다.

키 접두사

모든 TokenLab API 키는 sk-로 시작합니다.

오류 응답

상태 코드유형코드설명
401invalid_api_keyinvalid_api_keyAPI 키가 누락되었거나, 유효하지 않거나, 비활성 상태이거나, 취소됨
401expired_api_keyexpired_api_key키가 만료됨
402insufficient_balanceinsufficient_balance계정 잔액 부족
402quota_exceededquota_exceededAPI 키 사용 한도 도달
403permission_errormodel_not_allowed해당 키로 요청된 모델을 사용할 권한이 없음
403permission_erroruser_suspended, account_restricted계정에서 API를 사용할 수 없음
429rate_limit_exceededrate_limit_exceeded동일한 IP 주소에서 너무 많은 인증 실패 발생. Retry-After를 기다린 후 키를 수정하십시오. 401 오류가 반복되도록 두지 마십시오.

예시:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

이 페이지의 내용