API 레퍼런스

개요

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

베이스 URL

https://api.tokenlab.sh

인증

모든 API 엔드포인트는 Bearer 토큰을 사용한 인증이 필요합니다:

Authorization: Bearer sk-your-api-key

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

인터랙티브 플레이그라운드 안내: 이 문서 사이트의 플레이그라운드는 데모 전용이며 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= 쿼리 파라미터 인증을 지원합니다.

응답 형식

모든 응답은 일관된 형식을 따릅니다:

성공 응답

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4o",
  "choices": [...],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

라우팅 투명성

모든 응답에는 채널 정보가 포함된 _routing 필드가 포함됩니다:

{
  "id": "chatcmpl-abc123",
  ...,
  "_routing": {
    "channel": {
      "id": "ch_xxx",
      "name": "channel-name",
      "provider": "openai"
    },
    "cached": false,
    "retryCount": 0
  }
}

필드	설명
`channel.id`	사용된 채널 식별자
`channel.provider`	업스트림 프로바이더 (openai, anthropic 등)
`cached`	응답이 캐시에서 제공되었는지 여부
`retryCount`	재시도 횟수 (있는 경우)

오류 응답

{
  "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.0 사양 다운로드

핵심

텍스트

파일 및 배치

이미지

오디오 및 실시간

음악

비디오 및 자료

Worlds

3D

비동기 작업

Gemini 네이티브

관리

개요

베이스 URL

인증

지원되는 엔드포인트

채팅 및 텍스트 생성

임베딩 및 리랭크 (Rerank)

이미지

오디오

실시간

비디오

비동기 태스크

음악

3D 생성

모델

Gemini (v1beta)

응답 형식

성공 응답

라우팅 투명성

오류 응답

속도 제한 (Rate Limits)

OpenAPI 사양

OpenAPI 사양

​개요

​베이스 URL

​인증

​지원되는 엔드포인트

​채팅 및 텍스트 생성

​임베딩 및 리랭크 (Rerank)

​이미지

​오디오

​실시간

​비디오

​비동기 태스크

​음악

​3D 생성

​모델

​Gemini (v1beta)

​응답 형식

​성공 응답

​라우팅 투명성

​오류 응답

​속도 제한 (Rate Limits)

​OpenAPI 사양

OpenAPI 사양

개요

베이스 URL

인증

지원되는 엔드포인트

채팅 및 텍스트 생성

임베딩 및 리랭크 (Rerank)

이미지

오디오

실시간

비디오

비동기 태스크

음악

3D 생성

모델

Gemini (v1beta)

응답 형식

성공 응답

라우팅 투명성

오류 응답

속도 제한 (Rate Limits)

OpenAPI 사양