마이그레이션 가이드

TokenLab은 멀티 포맷을 지원합니다. OpenAI 호환 클라이언트, Anthropic 네이티브 Messages 호출, Gemini 네이티브 REST 호출 및 미디어 엔드포인트를 기존 형태 그대로 유지할 수 있습니다. 가장 안전한 마이그레이션 방법은 모든 워크로드를 하나의 범용 포맷으로 변환하는 것이 아닙니다. 애플리케이션이 필요로 하는 동작을 지원하는 경로를 선택하세요.

경로 매핑 (Route Mapping)Copy Anchor Link

빠른 마이그레이션 레시피Copy Anchor Link

OpenAI에서 TokenLab으로Copy Anchor Link

SDK base_url / baseURL만 https://api.tokenlab.sh/v1로 변경하세요. 롤아웃이 더 쉽다면 기존 OpenAI API 키 환경 변수 이름을 그대로 유지하고, GET /v1/models를 확인한 후 모델 ID를 교체하세요.

OpenRouter에서 TokenLab으로Copy Anchor Link

앱에서 이전에 OpenRouter의 OpenAI 호환 기본 URL을 사용하던 곳에 https://api.tokenlab.sh/v1을 사용하세요. 공급자 접두사가 붙은 모델 ID를 제거하고 /v1/models에서 제공하는 TokenLab 공개 모델 ID를 사용하세요. 워크로드에 Claude Messages나 Gemini generateContent가 필요한 경우, OpenAI 호환 채팅으로 강제하지 말고 네이티브 TokenLab 엔드포인트로 이동하세요.

LiteLLM에서 TokenLab으로Copy Anchor Link

LiteLLM의 custom_openai/<model> 경로와 api_base: https://api.tokenlab.sh/v1을 사용하세요. 애플리케이션 프롬프트를 변경하지 않고도 라우팅 정책을 변경할 수 있도록 LiteLLM 별칭을 실제 TokenLab 모델 ID와 분리하여 관리하세요.

TokenLab을 통한 Claude MessagesCopy Anchor Link

Anthropic SDK 클라이언트를 https://api.tokenlab.sh로 지정하고 messages.create를 호출하세요. SDK 기본 URL에 /v1을 추가하지 마세요. SDK가 /v1/messages 경로를 처리합니다.

TokenLab을 통한 Gemini NativeCopy Anchor Link

Gemini 페이로드를 https://api.tokenlab.sh/v1beta/models/{model}:generateContent에 유지하세요. 앱이 Gemini 동작에 의존하는 경우 Gemini 네이티브 contents, parts, 파일, 캐시된 콘텐츠, 함수 선언 및 내장 도구는 이 경로에 유지되어야 합니다.

OpenAI 호환 마이그레이션Copy Anchor Link

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Hello from TokenLab"}],
)

기존의 재시도, 타임아웃 및 스트리밍 코드는 유지하되, 프로덕션 트래픽을 보내기 전에 GET /v1/models로 모델 ID를 검증하세요. 이미지 생성의 경우 model을 명시적으로 전송하고, 이미지 모델은 채팅 모델보다 차이가 크므로 이미지 가이드를 읽어보시기 바랍니다.

Anthropic 마이그레이션Copy Anchor Link

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh",
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Reply with: Connected to TokenLab."}],
)

Claude 네이티브 도구 사용, 사고 과정(thinking flows) 및 Anthropic 메시지 의미론을 위해 /v1/messages를 사용하세요. 의도적으로 OpenAI 호환 동작 변경을 원하는 경우가 아니라면 Anthropic 전용 필드를 Chat Completions로 변환하지 마세요.

Gemini 마이그레이션Copy Anchor Link

curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'

앱이 Gemini 네이티브 동작에 의존하는 경우 Gemini 내장 도구, File API 참조, 캐시된 콘텐츠, 함수 선언 및 네이티브 콘텐츠 파트를 /v1beta 경로에 유지하세요.

미디어 마이그레이션Copy Anchor Link

1. GET /v1/models?recommended_for=image|video|music|3d를 쿼리합니다.
2. 목록 응답에서 GET /v1/models를 읽고, 가능한 경우 전체 GET /v1/models/{model}을 확인합니다.
3. 특히 이미지 엔드포인트의 경우 model을 명시적으로 전송합니다.
4. 비동기 작업을 위해 task_id, poll_url, 엔드포인트, 모델 및 자체 작업 ID를 저장합니다.
5. 비용 조정은 공급자 작업 ID가 아닌 사용 기록 및 billing_transaction_id를 통해 수행합니다.

미디어 워크로드는 지연 시간, 재시도 및 최종 에셋이 채팅 완료와 다르게 동작하므로 별도의 롤아웃 계획이 필요합니다.

프로덕션 롤아웃 계획Copy Anchor Link

마이그레이션 주의 사항Copy Anchor Link

• 앱이 네이티브 Anthropic, Gemini 또는 Responses 동작을 필요로 하는 경우 모든 모델을 하나의 OpenAI Chat Completions 경로 뒤에 두지 마세요.
• 이전 이미지 기본값을 가정하지 마세요. model을 명시적으로 전송하세요.
• 작업이 이미 생성되었는지 확인하지 않고 비동기 생성 요청을 재시도하지 마세요.
• 로그나 UI에 공급자별 식별자를 노출하지 마세요.
• 공급자 작업 ID로 결제 내역을 비교하지 마세요. TokenLab 사용 기록을 사용하세요.

API 참조Copy Anchor Link