시작하기
인증
API 키를 사용하여 TokenLab API 요청 인증하기
API 키
모델 호출 및 비공개 리소스에는 API 키가 필요합니다. GET /v1/models 및 GET /v1/models/{model}과 같은 공개 검색 엔드포인트는 키 없이도 작동합니다. 성공적인 검색 응답이 키가 정상적으로 작동함을 보장하지는 않으므로, Quickstart를 따라 모델 요청을 보내보시기 바랍니다. 저장된 전체 키를 사용하십시오. 키 목록에 표시된 접두사로는 인증할 수 없습니다.
OpenAI 호환 엔드포인트의 경우 다음과 같이 전송하십시오:
Authorization: Bearer sk-your-api-keyAnthropic 호환 /v1/messages 요청의 경우 다음을 사용할 수도 있습니다:
x-api-key: sk-your-api-keyGemini 호환 /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 키 발급받기
- TokenLab Console에 로그인합니다.
- API Keys를 엽니다.
- 새 키를 생성합니다.
- 식별 가능한 이름을 지정합니다.
- 한 번만 표시되므로 즉시 복사해 두십시오.
- 클라이언트 측 코드에 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-로 시작합니다.
오류 응답
| 상태 코드 | 유형 | 코드 | 설명 |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | API 키가 누락되었거나, 유효하지 않거나, 비활성 상태이거나, 취소됨 |
| 401 | expired_api_key | expired_api_key | 키가 만료됨 |
| 402 | insufficient_balance | insufficient_balance | 계정 잔액 부족 |
| 402 | quota_exceeded | quota_exceeded | API 키 사용 한도 도달 |
| 403 | permission_error | model_not_allowed | 해당 키로 요청된 모델을 사용할 권한이 없음 |
| 403 | permission_error | user_suspended, account_restricted | 계정에서 API를 사용할 수 없음 |
| 429 | rate_limit_exceeded | rate_limit_exceeded | 동일한 IP 주소에서 너무 많은 인증 실패 발생. Retry-After를 기다린 후 키를 수정하십시오. 401 오류가 반복되도록 두지 마십시오. |
예시:
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}