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

# SDK 마이그레이션

> 기존 SDK에서 K-Router로 전환하는 가이드

# SDK 마이그레이션 가이드

기존에 사용하던 SDK를 K-Router로 전환하는 방법을 안내합니다. **모델 이름만 `kr/` 네임스페이스로 변경하고, 엔드포인트를 K-Router로 지정하면 나머지 코드는 그대로 동작합니다.**

스트리밍, 멀티턴 대화, 함수 호출, temperature 등 모든 기능이 동일하게 지원됩니다.

***

## OpenAI SDK 사용자

`api_key`와 `base_url` 2줄만 변경합니다.

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  # Before
  # client = OpenAI(api_key="sk-...")

  # After
  client = OpenAI(
      api_key="kr-your-api-key",
      base_url="https://api.k-router.com/v1"
  )

  # 나머지 코드는 완전히 동일합니다
  response = client.chat.completions.create(
      model="kr/gpt54",
      messages=[
          {"role": "system", "content": "당신은 도움이 되는 어시스턴트입니다."},
          {"role": "user", "content": "안녕하세요"}
      ],
      temperature=0.7,
      max_tokens=1000
  )
  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  // Before
  // const client = new OpenAI({ apiKey: "sk-..." });

  // After
  const client = new OpenAI({
    apiKey: "kr-your-api-key",
    baseURL: "https://api.k-router.com/v1",
  });

  const response = await client.chat.completions.create({
    model: "kr/gpt54",
    messages: [{ role: "user", content: "안녕하세요" }],
    stream: true,
  });

  // 스트리밍도 그대로 동작합니다
  for await (const chunk of response) {
    process.stdout.write(chunk.choices[0]?.delta?.content || "");
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.k-router.com/v1/chat/completions \
    -H "Authorization: Bearer kr-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kr/gpt54",
      "messages": [{"role": "user", "content": "안녕하세요"}],
      "stream": true
    }'
  ```
</CodeGroup>

### 환경 변수로 전환

기존에 `OPENAI_API_KEY` 환경 변수를 사용하고 있다면:

```bash theme={null}
# .env 파일
OPENAI_API_KEY=kr-your-api-key
OPENAI_BASE_URL=https://api.k-router.com/v1
```

코드 변경 없이 환경 변수만 바꿔도 전환됩니다.

***

## Anthropic SDK 사용자

`api_key`와 `base_url` 2줄만 변경합니다.

<Warning>
  **중요:** Anthropic SDK는 `base_url`에 `/v1`을 붙이지 마세요. SDK가 자동으로 `/v1/messages` 경로를 추가합니다.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  from anthropic import Anthropic

  # Before
  # client = Anthropic(api_key="sk-ant-...")

  # After
  client = Anthropic(
      api_key="kr-your-api-key",
      base_url="https://api.k-router.com"  # /v1 없이!
  )

  # 나머지 코드는 완전히 동일합니다
  response = client.messages.create(
      model="kr/claude-sonnet-46",
      max_tokens=1024,
      system="당신은 도움이 되는 어시스턴트입니다.",
      messages=[{"role": "user", "content": "안녕하세요"}]
  )
  print(response.content[0].text)
  ```

  ```typescript TypeScript theme={null}
  import Anthropic from "@anthropic-ai/sdk";

  // Before
  // const client = new Anthropic({ apiKey: "sk-ant-..." });

  // After
  const client = new Anthropic({
    apiKey: "kr-your-api-key",
    baseURL: "https://api.k-router.com",  // /v1 없이!
  });

  const response = await client.messages.create({
    model: "kr/claude-sonnet-46",
    max_tokens: 1024,
    messages: [{ role: "user", content: "안녕하세요" }],
  });
  console.log(response.content[0].text);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.k-router.com/v1/messages \
    -H "x-api-key: kr-your-api-key" \
    -H "Content-Type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "kr/claude-sonnet-46",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "안녕하세요"}]
    }'
  ```
</CodeGroup>

### Anthropic 스트리밍

```python theme={null}
# 스트리밍도 그대로 동작합니다
with client.messages.stream(
    model="kr/claude-sonnet-46",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕하세요"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

### 환경 변수로 전환

```bash theme={null}
# .env 파일
ANTHROPIC_API_KEY=kr-your-api-key
ANTHROPIC_BASE_URL=https://api.k-router.com
```

***

## Google SDK 사용자

### 방법 1: OpenAI SDK로 전환 (권장)

`pip install openai` 후 OpenAI SDK를 사용하면 가장 간단합니다. 같은 Gemini 모델을 동일하게 사용할 수 있습니다.

<CodeGroup>
  ```python Python theme={null}
  # Before (Google SDK)
  from google import genai
  client = genai.Client(api_key="AIza...")
  response = client.models.generate_content(
      model="gemini-2.5-pro",
      contents="안녕하세요"
  )
  print(response.text)

  # After (OpenAI SDK — 같은 Gemini 모델)
  from openai import OpenAI
  client = OpenAI(
      api_key="kr-your-api-key",
      base_url="https://api.k-router.com/v1"
  )
  response = client.chat.completions.create(
      model="kr/gemini-25-pro",
      messages=[{"role": "user", "content": "안녕하세요"}]
  )
  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript theme={null}
  // Before (Google SDK)
  // const { GoogleGenerativeAI } = require("@google/generative-ai");
  // const genAI = new GoogleGenerativeAI("AIza...");

  // After (OpenAI SDK — 같은 Gemini 모델)
  import OpenAI from "openai";
  const client = new OpenAI({
    apiKey: "kr-your-api-key",
    baseURL: "https://api.k-router.com/v1",
  });

  const response = await client.chat.completions.create({
    model: "kr/gemini-25-pro",
    messages: [{ role: "user", content: "안녕하세요" }],
  });
  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.k-router.com/v1/chat/completions \
    -H "Authorization: Bearer kr-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kr/gemini-25-pro",
      "messages": [{"role": "user", "content": "안녕하세요"}]
    }'
  ```
</CodeGroup>

### 방법 2: Google 네이티브 SDK 유지

Google `genai` 라이브러리의 `base_url`을 커스텀하여 네이티브 SDK를 그대로 사용할 수도 있습니다.

```python theme={null}
from google import genai

client = genai.Client(
    api_key="kr-your-api-key",
    http_options=genai.types.HttpOptions(
        api_version="v1beta",
        base_url="https://api.k-router.com"
    )
)

response = client.models.generate_content(
    model="kr/gemini-25-pro",
    contents="안녕하세요"
)
print(response.text)
```

<Info>
  OpenAI SDK는 업계 표준으로 자리잡았으며, K-Router의 모든 모델(OpenAI, Anthropic, Google)을 하나의 SDK로 호출할 수 있어 가장 간편합니다. 특별한 이유가 없다면 방법 1을 권장합니다.
</Info>

***

## 공통 사항

### 모델 이름 규칙

모든 모델은 `kr/` 접두사를 사용합니다. 원본 모델 이름과의 매핑은 [모델 페이지](/models)를 참고하세요.

| 원본                  | K-Router              |
| ------------------- | --------------------- |
| `gpt-5.4`           | `kr/gpt54`            |
| `claude-sonnet-4.6` | `kr/claude-sonnet-46` |
| `gemini-2.5-pro`    | `kr/gemini-25-pro`    |

### 모든 기능이 그대로 동작합니다

* **스트리밍** — `stream: true` 또는 `.stream()` 메서드
* **멀티턴 대화** — messages 배열에 대화 기록 추가
* **시스템 프롬프트** — `system` role 또는 Anthropic `system` 파라미터
* **함수 호출 / Tool Use** — OpenAI function calling, Anthropic tool use 모두 지원
* **Temperature, top\_p, max\_tokens** — 모든 생성 파라미터 지원