API 레퍼런스

개요

TokenLab는 네이티브 우선이며 OpenAI 호환입니다. 네이티브 동작이 필요할 때는 Anthropic에는 POST /v1/messages, Gemini에는 /v1beta/models/...:generateContent와 같은 공급자 네이티브 경로를 사용하고, 기존 OpenAI 스타일 SDK나 도구를 마이그레이션할 때는 OpenAI 호환 /v1 엔드포인트를 사용하세요. POST /v1/responses는 Responses 전용 동작을 위한 고급 선택 경로로 남아 있습니다.

베이스 URL

https://api.tokenlab.sh

인증

모델 요청에는 TokenLab API 키를 사용합니다. 표준 인증 헤더는 다음과 같습니다:

Authorization: Bearer sk-your-api-key

GET /v1/models, GET /v1/models/{model}, GET /v1/pricing은 공개되어 키가 필요하지 않습니다. Anthropic Messages는 x-api-key도 지원하고, Gemini는 Bearer 외에 x-goog-api-key 또는 ?key=도 지원합니다. /v1/management/*에는 관리 토큰(mt-...)이 필요합니다.

대시보드에서 API 키를 확인하세요.

생성 요청은 X-TokenLab-Delivery-Policy: auto | verified | official을 지원합니다. 헤더, API 키 설정, 워크스페이스 기본값 순으로 우선합니다. auto는 TokenLab Verified를 먼저 사용하고 필요하면 Official을 사용하며, 완료한 방식에 따라 과금됩니다. verified는 TokenLab 가격을, official은 모델 제조사의 공개 가격을 기준으로 하며 실제 요금은 TokenLab 표시 가격을 따릅니다. Realtime은 키 또는 워크스페이스 설정을 사용하고 쿼리 재정의는 지원하지 않습니다. 잘못된 헤더는 400, 이용할 수 없는 방식은 503 delivery_tier_unavailable과 요청 ID를 반환합니다.

인터랙티브 플레이그라운드 안내: 이 문서 사이트의 플레이그라운드는 데모 전용이며 API 키 입력을 지원하지 않습니다. API를 테스트하려면 다음을 사용하세요:

cURL - 예시 명령어를 복사하고 sk-your-api-key를 실제 키로 교체하세요.
Postman - 당사의 OpenAPI 사양을 가져오기 하세요.
SDK - 당사의 베이스 URL과 함께 OpenAI/Anthropic SDK를 사용하세요.

지원되는 엔드포인트

채팅 및 텍스트 생성

엔드포인트	메서드	설명
`/v1/chat/completions`	POST	OpenAI 호환 채팅 완성
`/v1/messages`	POST	Anthropic 호환 메시지 API
`/v1/responses`	POST	OpenAI Responses API

임베딩 및 리랭크 (Rerank)

엔드포인트	메서드	설명
`/v1/embeddings`	POST	텍스트 임베딩 생성
`/v1/rerank`	POST	문서 리랭크

이미지

엔드포인트	메서드	설명
`/v1/images/generations`	POST	텍스트로 이미지 생성
`/v1/images/edits`	POST	이미지 편집
`/v1/images/generations/{id}`	GET	태스크 기반 이미지 응답을 위한 이미지 태스크 상태 경로

이미지 모델은 완성 이미지 또는 비동기 작업을 반환할 수 있습니다. 응답에 poll_url이 있으면 해당 URL로 작업을 조회하세요.

오디오

엔드포인트	메서드	설명
`/v1/audio/speech`	POST	텍스트 음성 변환 (TTS)
`/v1/audio/transcriptions`	POST	음성 텍스트 변환 (STT)

실시간

엔드포인트	메서드	설명
`/v1/realtime?model={model}`	WS	실시간 WebSocket 세션

/v1/realtime은 WebSocket 업그레이드 요청에 사용합니다. 일반 GET /v1/realtime은 WebSocket 라우트를 직접 확인할 수 없는 클라이언트를 위해 엔드포인트 메타데이터를 반환합니다. 이는 OpenAI Realtime REST 표면이 아닙니다. client secret, translation client secret, Calls, legacy beta session 엔드포인트는 현재 제공하지 않습니다.

비디오

엔드포인트	메서드	설명
`/v1/videos/generations`	POST	비디오 생성 태스크 생성
`/v1/tasks/{id}`	GET	비디오 작업에 대한 비동기 태스크 상태 조회
`/v1/videos/generations/{id}`	GET	레거시 호환 비디오 태스크 상태 경로

신규 클라이언트의 경우 /v1/tasks/{id}를 권장하며 생성 응답에서 반환된 poll_url을 따르세요. /v1/videos/generations/{id}는 하위 호환성을 위해서만 유지됩니다.

비동기 태스크

엔드포인트	메서드	설명
`/v1/tasks/{id}`	GET	통합 비동기 태스크 상태 엔드포인트. 반환된 `poll_url`을 따를 때 권장됩니다.

이 엔드포인트는 비디오, 음악, 3D에 국한되지 않습니다. 일부 이미지 태스크도 /v1/tasks/{id}를 표준 폴링 경로로 사용할 수 있습니다.

음악

엔드포인트	메서드	설명
`/v1/music/generations`	POST	음악 생성 태스크 생성
`/v1/music/generations/{id}`	GET	음악 전용 상태 경로

신규 클라이언트의 경우 반환된 poll_url을 우선적으로 사용하세요. 고정된 태스크 상태 엔드포인트가 필요한 경우 /v1/tasks/{id}를 사용하고, /v1/music/generations/{id}는 음악 전용 호환성 경로로 유지하세요.

3D 생성

엔드포인트	메서드	설명
`/v1/3d/generations`	POST	3D 모델 생성 태스크 생성
`/v1/3d/generations/{id}`	GET	3D 전용 상태 경로

신규 클라이언트의 경우 반환된 poll_url을 우선적으로 사용하세요. 고정된 태스크 상태 엔드포인트가 필요한 경우 /v1/tasks/{id}를 사용하고, /v1/3d/generations/{id}는 3D 전용 호환성 경로로 유지하세요.

모델

엔드포인트	메서드	설명
`/v1/models`	GET	사용 가능한 모든 모델 목록 조회
`/v1/models/{model}`	GET	특정 모델 정보 조회

Gemini (v1beta)

네이티브 Google Gemini API 형식 지원:

엔드포인트	메서드	설명
`/v1beta/models/{model}:generateContent`	POST	콘텐츠 생성 (Gemini 형식)
`/v1beta/models/{model}:streamGenerateContent`	POST	스트림 콘텐츠 생성 (Gemini 형식)

Gemini 엔드포인트는 표준 Bearer 토큰 외에 ?key= 쿼리 파라미터 인증을 지원합니다.

응답 형식

각 엔드포인트는 해당 API 형식을 유지합니다. 아래 성공 및 오류 예시는 Chat Completions 형식입니다.

성공 응답

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.6-terra",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

라우팅 투명성

TokenLab은 공개 응답 본문에 제공자, 채널, 정책 또는 자격 증명 세부 정보를 노출하지 않습니다. _routing 또는 기타 내부 라우팅 필드를 공개 API 계약의 일부로 의존하지 마세요.

디버깅 및 지원에는 응답에 실제로 포함된 경우 다음 공개 응답 헤더를 사용할 수 있습니다.

헤더	설명
`X-Routing-Time-MS`	라우트 선택 시간(사용 가능한 경우)
`X-Request-ID`	지원 및 디버깅용 요청 식별자(사용 가능한 경우)
`X-Task-ID`	태스크 기반 응답의 공개 비동기 태스크 식별자(사용 가능한 경우)
`X-Billing-Transaction-ID`	최종 과금 후의 과금 트랜잭션 식별자(사용 가능한 경우)

오류 응답

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

속도 제한 (Rate Limits)

속도 제한은 역할 기반이며 관리자가 설정할 수 있습니다. 기본값은 다음과 같습니다:

역할	분당 요청 수 (Requests/min)
User	1,000
Partner	10,000
VIP	10,000

맞춤형 속도 제한은 고객 지원에 문의하세요. 정확한 값은 계정 설정에 따라 다를 수 있습니다.

속도 제한을 초과하면 API는 429 상태 코드와 함께 대기 시간을 나타내는 Retry-After 헤더를 반환합니다.

OpenAPI 사양

전체 OpenAPI 3.1 사양 다운로드

API 레퍼런스

개요Copy Anchor Link

베이스 URLCopy Anchor Link

인증Copy Anchor Link

지원되는 엔드포인트Copy Anchor Link

채팅 및 텍스트 생성Copy Anchor Link

임베딩 및 리랭크 (Rerank)Copy Anchor Link

이미지Copy Anchor Link

오디오Copy Anchor Link

실시간Copy Anchor Link

비디오Copy Anchor Link

비동기 태스크Copy Anchor Link

음악Copy Anchor Link

3D 생성Copy Anchor Link

모델Copy Anchor Link

Gemini (v1beta)Copy Anchor Link

응답 형식Copy Anchor Link

성공 응답Copy Anchor Link

라우팅 투명성Copy Anchor Link

오류 응답Copy Anchor Link

속도 제한 (Rate Limits)Copy Anchor Link

OpenAPI 사양Copy Anchor Link

OpenAPI 사양

이 페이지의 내용

개요

베이스 URL

인증

지원되는 엔드포인트

채팅 및 텍스트 생성

임베딩 및 리랭크 (Rerank)

이미지

오디오

실시간

비디오

비동기 태스크

음악

3D 생성

모델

Gemini (v1beta)

응답 형식

성공 응답

라우팅 투명성

오류 응답

속도 제한 (Rate Limits)

OpenAPI 사양