> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 마이그레이션 가이드

> OpenAI, Anthropic, Gemini 및 미디어 워크로드를 TokenLab으로 소규모, 프로덕션 안전한 변경으로 이동합니다.

TokenLab은 다중 형식입니다: OpenAI 호환 클라이언트, Anthropic 네이티브 Messages 호출, Gemini 네이티브 REST 호출 및 미디어 엔드포인트를 자연스러운 형태로 유지할 수 있습니다. 가장 안전한 마이그레이션은 모든 워크로드를 하나의 보편적인 형식으로 변환하지 않는 것입니다. 애플리케이션에 필요한 동작을 소유하는 경로를 선택하십시오.

## 경로 매핑

| 기존 워크로드       | TokenLab 기본 URL              | 주요 엔드포인트                                | 마이그레이션 노트                                           |
| ------------- | ---------------------------- | --------------------------------------- | --------------------------------------------------- |
| OpenAI 채팅 완료  | `https://api.tokenlab.sh/v1` | `/chat/completions`                     | OpenAI 호환 채팅 및 함수 호출을 위한 가장 작은 변경                   |
| OpenAI 응답     | `https://api.tokenlab.sh/v1` | `/responses`                            | 앱이 응답 특정 입력, 도구 또는 출력 처리를 의존할 때 사용                  |
| Anthropic SDK | `https://api.tokenlab.sh`    | `/v1/messages`                          | SDK 기본 URL에 `/v1`을 추가하지 마십시오                        |
| Gemini REST   | `https://api.tokenlab.sh`    | `/v1beta/models/:model:generateContent` | Gemini 경로에서 Gemini 네이티브 필드를 유지하십시오                  |
| 미디어 생성        | `https://api.tokenlab.sh/v1` | `/images`, `/videos`, `/music`, `/3d`   | `recommended_for`로 모델을 발견하고 문서화된 곳에서 비동기 폴링을 기대하십시오 |
| 관리 및 청구       | `https://api.tokenlab.sh/v1` | `/management/...`                       | 서버 측 사용 및 청구 조정을 위해 관리 토큰을 사용하십시오                   |

## OpenAI 호환 마이그레이션

```python theme={null}
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.4",
    messages=[{"role": "user", "content": "Hello from TokenLab"}],
)
```

기존의 재시도, 타임아웃 및 스트리밍 코드를 유지하되, 프로덕션 트래픽 전에 `GET /v1/models`로 모델 ID를 검증하십시오. 이미지 생성을 위해서는 `model`을 명시적으로 전송하고 이미지 가이드를 읽으십시오. 이미지 모델은 채팅 모델보다 차이가 큽니다.

## Anthropic 마이그레이션

```python theme={null}
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-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain TokenLab in one sentence."}],
)
```

Claude 네이티브 도구 사용, 사고 흐름 및 Anthropic 메시지 의미론을 위해 `/v1/messages`를 사용하십시오. OpenAI 호환 동작 변경을 의도하지 않는 한, Chat Completions를 통해 Anthropic 전용 필드를 변환하지 마십시오.

## Gemini 마이그레이션

```bash theme={null}
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 내장 도구, 파일 API 참조, 캐시된 콘텐츠, 함수 선언 및 네이티브 콘텐츠 부분을 `/v1beta`에서 유지하십시오.

## 미디어 마이그레이션

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

미디어 워크로드는 지연, 재시도 및 최종 자산이 채팅 완료와 다르게 동작하기 때문에 자체 롤아웃 계획이 필요합니다.

## 프로덕션 롤아웃 계획

| 단계           | 목표                                        | 체크                                   |
| ------------ | ----------------------------------------- | ------------------------------------ |
| 1. 인벤토리      | 엔드포인트, 모델, 요청 필드, 스트리밍/비동기 동작 및 청구 소유자 목록 | 숨겨진 제공자 전용 필드는 공개로 가정하지 않음           |
| 2. 단일 경로 파일럿 | 하나의 엔드포인트와 하나의 모델 패밀리 이동                  | 응답 형상, 비용 및 로그가 기대와 일치               |
| 3. 그림자 또는 샘플 | 선택된 출력을 이전 제공자와 비교                        | 사용자 가시 품질 및 지연이 수용 가능                |
| 4. 점진적 롤아웃   | 키, 조직 또는 기능 플래그에 따라 트래픽 증가                | `4xx`, `5xx`, 지연, 균형 및 중복 비동기 작업을 주의 |
| 5. 정리        | 안정적인 사용 후에만 이전 제공자 경로 제거                  | 롤백 경로 및 지원 플레이북이 문서화됨                |

## 마이그레이션 함정

* 앱이 네이티브 Anthropic, Gemini 또는 Responses 동작을 필요로 하는 경우 모든 모델을 하나의 OpenAI Chat Completions 경로 뒤에 두지 마십시오.
* 이전 이미지 기본값을 가정하지 마십시오. `model`을 명시적으로 전송하십시오.
* 작업이 이미 생성되었는지 확인하지 않고 비동기 생성 요청을 재시도하지 마십시오.
* 로그나 UI에 제공자 라우팅 메타데이터를 노출하지 마십시오.
* 제공자 작업 ID와 청구를 비교하지 마십시오. TokenLab 사용 기록을 사용하십시오.

## API 참조

| 주제            | 참조                                                           |
| ------------- | ------------------------------------------------------------ |
| 다중 형식 API     | [다중 형식 API](/ko/guides/api-formats)                          |
| OpenAI SDK    | [OpenAI SDK](/ko/integrations/openai-sdk)                    |
| Anthropic SDK | [Anthropic SDK](/ko/integrations/anthropic-sdk)              |
| Gemini 네이티브   | [Gemini 네이티브 API](/ko/api-reference/gemini/generate-content) |
| 이미지 생성        | [이미지 생성](/ko/guides/image-generation)                        |
| 비동기 작업 및 폴링   | [비동기 작업 및 폴링](/ko/guides/async-jobs-polling)                 |