5분 만에 OpenAI에서 TokenLab으로 마이그레이션하기

기존 제공업체를 떠날 때 베이스 URL을 변경하는 것은 쉬운 부분입니다. 마이그레이션이 실패하는 지점은 바로 오류 경로입니다. OpenAI에서 TokenLab으로 마이그레이션하려면 OpenAI SDK 클라이언트에서 base_url과 api_key라는 두 가지 값을 변경해야 합니다. 이 가이드의 나머지 부분에서는 해당 변경과 관련하여 확인해야 할 사항을 다룹니다. 즉, 전송하는 모델 ID, 현재 가격, 스트리밍, 도구 호출(tool calls), 오류 처리, 타임아웃 및 결제와 관련된 내용입니다. 아래의 사실들은 TokenLab 문서와 라이브 모델 API에서 가져온 것이며, 각각 관찰된 날짜가 명시되어 있습니다.

핵심 요약

• 핵심 변경 사항은 두 가지 값입니다: TokenLab 베이스 URL https://api.tokenlab.sh/v1과 TokenLab API 키(sk-로 시작함).
• TokenLab은 Chat Completions 및 Responses에 대한 OpenAI SDK 지원을 문서화하고 있습니다. 선택적 매개변수, 도구 옵션 및 Responses 전용 필드는 여전히 선택한 모델에 따라 다릅니다.
• 결정을 내리기 전에 라이브 API에서 모델의 가격을 확인하십시오. 2026년 10월 3일 기준, gpt-5.5는 100만 토큰당 입력 1.50달러, 출력 9.00달러로 책정되었습니다.
• 프로덕션 트래픽을 옮기기 전에 마지막에 있는 체크리스트를 실행하십시오. 대부분의 예상치 못한 문제는 성공 경로(happy path)가 아닌 오류 처리, 타임아웃, 결제에서 발생합니다.

OpenAI에서 TokenLab으로 마이그레이션하기 위한 두 가지 값 변경

키부터 시작하십시오. Quickstart(2026년 10월 3일 관찰)에 따라 계정을 만들고 API 키를 생성한 뒤 전체 값을 즉시 저장하십시오. 키는 한 번만 표시되며, 키 목록의 접두사로는 요청을 인증할 수 없습니다. 첫 번째 호출 전에 잔액을 확인하십시오. 요청은 선택한 모델의 현재 가격으로 청구됩니다.

그런 다음 클라이언트를 변경하십시오. 마이그레이션 가이드(2026년 10월 3일 관찰)에서는 base_url / baseURL을 https://api.tokenlab.sh/v1으로 설정하고, 키를 교체한 뒤 GET /v1/models에서 모델 ID를 선택하는 방법을 설명합니다.

예를 들어, 구성에 gpt-5.5라는 문자열이 있는 서비스를 가정해 보겠습니다. 두 가지 값을 변경한 후에도 해당 문자열은 유효한 요청이지만, 여전히 먼저 ID를 확인하는 것이 좋습니다. GET /v1/models 및 GET /v1/models/{model}은 공개 검색 엔드포인트이며 키 없이도 작동합니다.

Python

import os
from openai import OpenAI

# 이전: client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

// 이전: new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
const client = new OpenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1',
  timeout: 30_000,
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Say hello"}]}'

위의 처음 두 예제에 있는 타임아웃 및 재시도 설정은 30초 타임아웃과 0회 SDK 재시도를 사용하는 Quickstart 예제(2026년 10월 3일 관찰)를 반영합니다. 테스트 중에는 실패한 요청이 조용히 재시도되지 않고 눈에 띄도록 재시도 횟수를 0으로 유지합니다.

클라이언트 구성에서 베이스 URL을 명시적으로 전달하십시오. SDK 가이드(2026년 10월 3일 관찰)는 이전 환경 변수 별칭에 의존하는 것보다 이 방법을 권장합니다. 키는 서버와 비밀 관리자(secret manager)에 보관하고, 클라이언트 측 코드에는 절대 넣지 마십시오.

모델 ID 선택 및 가격 확인

마이그레이션 시 모델 ID나 가격을 가정해서는 안 됩니다. 둘 다 모델 API에 있습니다. 2026년 10월 3일에 https://api.tokenlab.sh/v1/models/gpt-5.5와 https://api.tokenlab.sh/v1/models/laguna-s-2.1을 확인했습니다. 두 모델의 가격은 2026년 10월 2일 16:53:30.068Z에 마지막으로 업데이트되었습니다.

필드	gpt-5.5	laguna-s-2.1
수명 주기 단계	active	active
최대 입력 / 출력 토큰	1,000,000 / 128,000	1,048,576 / 131,072
허용된 요청 형식	openai_chat_completions, openai_responses	openai_chat_completions
나열된 기능	coding, json-mode, prompt-cache, reasoning, tool-use, vision	tool-use
입력, 100만 토큰당 USD	1.5	0.1
출력, 100만 토큰당 USD	9	0.2
캐시 읽기, 100만 토큰당 USD	0.15	0.01

출처: gpt-5.5 및 laguna-s-2.1 (모두 2026년 10월 3일 관찰).

이 요금을 계산해 보면 다음과 같습니다. 캐시 적중 없이 입력 토큰 100만 개와 출력 토큰 10만 개가 필요한 작업을 가정합니다.

• gpt-5.5: 1 × $1.50 + 0.1 × $9.00 = $1.50 + $0.90 = $2.40.
• laguna-s-2.1: 1 × $0.10 + 0.1 × $0.20 = $0.10 + $0.02 = $0.12.

이는 나열된 토큰당 요금을 기준으로 한 추정치입니다. 최종 청구 금액은 사용량(Usage) 기록을 따릅니다. 토큰화 방식은 모델마다 다르므로 동일한 텍스트라도 모델에 따라 토큰 수가 다르게 생성됩니다.

여기서 비용 절감을 주장하는 것은 아닙니다. 현재 지불하는 비용과 비교하려면 전환하는 날에 TokenLab 요금을 귀하의 OpenAI 청구서나 OpenAI 가격 페이지와 나란히 놓고 비교하십시오. 가격은 변동될 수 있으며, 결제 가이드(2026년 10월 3일 관찰)에서는 복사한 가격표를 하드코딩하지 말라고 명시하고 있습니다. 대신 현재 값을 확인하려면 GET /v1/models/:model/pricing을 참조하십시오.

다른 모델 ID도 동일한 패턴을 따릅니다. 문서 예제에서는 Chat Completions에 gpt-5.6-terra와 gpt-5.6-luna를, 자체 경로에는 claude-sonnet-5와 gemini-3.5-flash를 사용합니다. 트래픽을 보내기 전에 각 모델이 허용하는 형식을 읽어보십시오. 더 광범위한 비교는 모델 디렉토리, OpenRouter vs TokenLab 비교, 모델 순위를 참조하십시오. 이미지 및 비디오 팀은 2026년 최고의 AI 이미지 모델 API와 2026년 최고의 AI 비디오 모델 API부터 시작할 수 있습니다. 코딩 작업의 경우 코딩을 위한 최고의 AI 모델을 참조하십시오.

OpenAI에서 TokenLab으로 마이그레이션할 때 다음으로 확인할 사항

TokenLab은 OpenAI SDK가 Chat Completions 및 Responses와 작동한다고 문서화하고 있습니다. 이는 요청 및 응답 형식과의 호환성을 의미하며, 모든 모델이 동일하게 동작한다는 약속은 아닙니다. API 형식 가이드(2026년 10월 3일 관찰)에 따르면 선택적 매개변수는 모델에 따라 다릅니다. 또한 모델이 4가지 API 형식을 모두 수용하는 것은 아니며, tokenlab.accepted_request_formats를 통해 수용 여부를 확인할 수 있습니다. 아래의 각 영역을 실제 트래픽으로 테스트해야 할 대상으로 간주하십시오.

스트리밍

stream: true는 부분 메시지 델타를 서버 전송 이벤트(SSE)로 보냅니다. Create Chat Completion 참조(2026년 10월 3일 관찰)에 문서화된 대로, 스트림 청크 내에서 토큰 사용량을 받으려면 stream_options에 include_usage: true를 설정하십시오.

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

계획해야 할 두 가지 동작이 있습니다. 출력이 도착한 후 스트림이 중단되면 이를 완전한 응답으로 간주하지 마십시오. 오류 처리 가이드(2026년 10월 3일 관찰)에서는 이를 반복할 경우 다른 출력이 생성되거나 두 번째 요금이 청구될 수 있다고 경고합니다. 또한 스트리밍은 결제보다 먼저 완료될 수 있으므로 결제 ID가 없을 수도 있습니다.

도구 호출(Tool calls)

Chat Completions 참조에는 tools, tool_choice 및 parallel_tool_calls가 나열되어 있습니다. 병렬 호출은 "선택한 모델이 지원할 때" 작동한다고 명시되어 있습니다. 함수 호출은 "선택한 모델이 지원함"으로 문서화되어 있으므로 기능 목록을 확인하십시오. 위의 표에서 gpt-5.5와 laguna-s-2.1 모두 tool-use를 나열하지만, gpt-5.5만 json-mode와 vision을 나열합니다. 장난감 예제가 아닌 실제 도구 스키마를 보내고 반환된 인수가 파싱되는지 확인하십시오.

Claude 모델을 호출할 계획이라면 마이그레이션 가이드의 규칙을 참고하십시오. Claude 도구 호출, 사고 블록(thinking blocks) 및 Anthropic 메시지 필드는 /v1/messages에 속하며, Chat Completions는 이를 보장하지 않습니다.

오류 형태

Chat Completions 및 Responses는 OpenAI 스타일의 error 객체를 반환합니다. 오류 처리 가이드에 따르면 message와 type만 항상 존재합니다. code, param, retryable, retry_after와 같은 필드는 관련이 있을 때만 나타납니다. 메시지 텍스트가 아닌 HTTP 상태 및 code를 기준으로 분기하고, 파서가 누락된 필드를 허용하도록 만드십시오. Anthropic Messages와 Gemini는 자체 오류 형식을 유지하므로 하나의 파서가 모든 경로를 커버할 수는 없습니다.

상태	코드	의미
401	invalid_api_key	키가 누락되었거나, 유효하지 않거나, 비활성 상태이거나, 취소됨
401	expired_api_key	키가 만료됨
402	insufficient_balance	계정 잔액이 요청을 충당할 수 없음
402	quota_exceeded	키 자체의 사용량 제한에 도달함
403	model_not_allowed	이 키는 요청된 모델을 사용할 수 없음
429	rate_limit_exceeded	요청이 너무 많음; Retry-After를 기다리십시오

출처: 인증 및 오류 처리 (2026년 10월 3일 관찰).

이 표는 일반적인 가정을 바로잡습니다. 잔액 부족은 401이 아니라 402입니다. 현재 코드가 모든 4xx를 잘못된 키로 처리한다면 업데이트하십시오.

타임아웃 및 재시도

마이그레이션 가이드에 따르면 기존 재시도, 타임아웃 및 스트리밍 코드는 일반적으로 그대로 유지할 수 있습니다. 문서화된 재시도 규칙에 따라 검토하십시오.

• 400, 401, 402, 403, 404 또는 413 응답은 변경하지 않고 반복하지 마십시오.
• 서버에서 제공한 지연 시간 이후에 429를 재시도하십시오.
• retryable이 true인 경우에만 500~504를 재시도하고 retry_after를 준수하십시오.
• 503 all_channels_failed는 retryable: false로 반환될 수 있습니다. 이 경우 해당 작업은 선택한 전달 계층에 공급이 없으므로 반복해도 도움이 되지 않습니다.

응답 헤더의 요청 ID를 모델 및 자체 작업 ID와 함께 저장하십시오. 이는 조사에 필요한 정보입니다.

결제

결제 가이드에 따르면 잔액 하나로 모든 모델을 사용할 수 있으며 구독이나 최소 지불 금액은 없습니다. 완료된 각 요청은 해당 요청을 생성한 전달 옵션에 대해 한 번 청구됩니다. 옵션은 TokenLab Verified, Official, Auto가 있으며, Auto는 Verified를 먼저 시도한 후 Official을 시도합니다. 강제 종료를 원하면 각 API 키에 지출 한도를 설정하십시오. 한도에 도달하면 해당 키를 사용하는 요청은 402를 반환합니다.

비스트리밍 OpenAI 호환 응답에는 응답이 전송되기 전에 결제가 완료되면 billing_transaction_id가 포함됩니다. 이는 X-Billing-Transaction-ID 헤더에도 나타날 수 있습니다. 이를 저장하고 자체 토큰 계산이 아닌 사용량(Usage) 페이지와 대조하십시오.

OpenAI에서 TokenLab으로 마이그레이션 후 확인 체크리스트

프로덕션 트래픽을 옮기기 전에 스테이징 키를 사용하여 다음 순서대로 실행하십시오. 각 행은 위에 문서화된 동작을 추적합니다.

단계	실행 내용	확인 사항
1. 모델 검색	GET /v1/models/gpt-5.5 (키 불필요)	수명 주기 active 및 계획 중인 허용 형식
2. 인증된 요청	위의 Python 또는 cURL 샘플	비어 있지 않은 답변; 요청이 모델, 상태, 사용량과 함께 Requests 뷰에 나타남
3. 사용량 필드	비스트리밍 응답에서 usage 읽기	prompt_tokens, completion_tokens, total_tokens
4. 스트리밍	stream: true 및 include_usage: true	SSE 청크 및 사용량; 중단된 스트림은 불완전한 것으로 처리됨
5. 도구 호출	실제 tools 및 tool_choice	인수가 파싱되고 스키마와 일치함
6. Vision 또는 JSON 모드	모델이 vision 또는 json-mode를 나열한 경우에만	예상 출력; 기능이 나열되지 않은 경우 테스트 건너뜀
7. 잘못된 키	삭제되었거나 잘못된 키로 요청	401 invalid_api_key
8. 잔액 부족 또는 키 한도	낮은 한도의 키 또는 빈 워크스페이스 사용	402 insufficient_balance 또는 quota_exceeded
9. 모델 제한	키의 모델 목록을 제한한 후 다른 모델 요청	403 model_not_allowed
10. 타임아웃 및 재시도	스테이징에서 타임아웃 강제	코드가 retryable 및 retry_after에 따라서만 재시도함
11. 결제	billing_transaction_id 및 사용량을 추정치와 비교	청구 금액이 모델의 현재 가격 및 기록된 토큰과 일치함

표의 내용이 모두 통과되면 프로덕션 구성을 변경하고 배포하십시오. 사용량(Usage)을 통해 새로운 경로가 안정적임이 확인될 때까지 이전 OpenAI 키를 활성 상태로 유지하십시오.

자주 묻는 질문

OpenAI에서 전환할 때 모델 이름을 변경해야 하나요?

반드시 그렇지는 않지만 각각 확인하십시오. TokenLab 모델 ID는 정확한 문자열이므로 GET /v1/models 또는 GET /v1/models/{model}로 확인하십시오. 2026년 10월 3일 기준 라이브 API는 gpt-5.5를 active로 나열했습니다. 요청이 model_not_found를 반환하면 ID를 알 수 없거나 사용할 수 없는 것입니다. 모델 목록을 읽고 현재 ID를 사용하십시오.

스트리밍과 도구 호출이 OpenAI API와 정확히 똑같이 동작하나요?

TokenLab은 SSE를 통한 스트리밍과 OpenAI 호환 요청 형식을 통한 함수 호출을 문서화하고 있습니다. 또한 지원되는 옵션은 선택한 모델에 따라 다르다고 명시되어 있습니다. 따라서 결과를 동일하지는 않지만 호환되는 것으로 간주합니다. 실행하려는 특정 모델로 스트리밍, tools, tool_choice 및 사용하는 모든 response_format을 테스트하십시오.

잔액이 소진되면 어떤 상태 코드를 받나요?

insufficient_balance 코드와 함께 HTTP 402를 받습니다. 자체 지출 한도에 도달한 키도 quota_exceeded와 함께 402를 반환합니다. 누락되었거나, 유효하지 않거나, 취소된 키는 401을 반환합니다. 이 중 어떤 것도 변경하지 않고 재시도하지 마십시오. 잔액을 충전하거나, 키 한도를 높이거나, 키를 교체하십시오.

동일한 OpenAI 클라이언트에서 Claude나 Gemini 모델을 호출할 수 있나요?

모델 카탈로그에는 claude-sonnet-5와 gemini-3.5-flash가 요청 형식 중 openai_chat_completions와 함께 나열되어 있습니다. 따라서 기본 채팅은 동일한 클라이언트를 통해 진행할 수 있습니다. 사고 블록이나 Claude 도구 사용과 같은 Claude 전용 필드는 /v1/messages에 속합니다. Gemini 네이티브 필드는 /v1beta 경로에 유지됩니다. 대화당 하나의 API 형식을 유지하십시오.

TokenLab에서 빌드 시작하기

TokenLab에서 키를 생성하고, 베이스 URL을 https://api.tokenlab.sh/v1으로 설정한 뒤, 프로덕션을 건드리기 전에 Quickstart 요청을 실행하십시오.