블로그 목록으로
가이드·2026년 5월 23일·6분 분량

OpenAI SDK로 Claude 호출 — 한 줄만 변경하고 코드베이스는 그대로 유지

Anthropic의 SDK는 훌륭하지만 생태계는 OpenAI의 SDK를 표준으로 사용합니다. 수정하지 않은 OpenAI Python 및 Node SDK로 Claude Opus 4.7, Sonnet 4.6, Haiku 4.5를 호출하는 방법을 설명합니다 — 스트리밍, 도구 사용, 비전 포함

Anthropic의 자체 SDK는 훌륭하지만, 전체 AI 생태계는 OpenAI 클라이언트 형태를 표준화했습니다. 모든 예제, 프레임워크 어댑터 및 "hello world" 튜토리얼은 OpenAI(...) 인스턴스가 있다고 가정합니다. Anthropic SDK를 직접 호출하도록 코드를 마이그레이션하는 것은 상당한 리팩터링입니다.

그럴 필요는 없습니다. 이 글에서는 OpenAI SDK를 변경하지 않고 Claude Opus 4.7, Sonnet 4.6 및 Haiku 4.5를 호출하는 방법을 보여줍니다 — Kunavo를 통해 호출을 라우팅하는 방식입니다. 동일한 SDK, 동일한 타입, 동일한 스트리밍, 동일한 도구 사용이 가능합니다. 변경되는 줄은 base_url 하나뿐입니다.

최소 변경 사항

Python의 openai 패키지가 이미 설치되어 있다면 전체 마이그레이션은 다음과 같습니다.

main.py
from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",   # the only line that changes
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",              # a Claude slug, not gpt-4o
    messages=[
        {"role": "system", "content": "You are a senior platform engineer."},
        {"role": "user",   "content": "Critique this SQL migration..."},
    ],
)
print(resp.choices[0].message.content)

api_key을 Kunavo 키로 바꿉니다（/app/keys에서 생성）. base_url는 당사의 게이트웨이를 가리킵니다. 모델 ID를 gpt-4o에서 Claude 슬러그인 claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5 중 하나로 변경합니다. 요청 본문, 응답 형식 및 SDK의 모든 헬퍼는 OpenAI를 대상으로 할 때와 정확히 동일하게 작동합니다.

스트리밍

스트리밍도 동일하게 작동합니다. Kunavo는 Anthropic의 SSE 청크를 OpenAI의 chat.completion.chunk 형식으로 전달하므로 기존 비동기 반복 패턴을 수정 없이 사용할 수 있습니다.

stream.py
for chunk in client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Explain Raft in 200 words."}],
    stream=True,
):
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

도구 사용 / 함수 호출

Anthropic의 도구 사용 프로토콜은 의미상 OpenAI의 함수 호출과 동일하며 와이어 수준에서만 다릅니다. Kunavo는 tools 배열, 응답 tool_calls 및 후속 tool 메시지를 양방향으로 변환합니다. tool_choice="auto", "none" 또는 이름이 지정된 도구를 사용해도 모두 매핑됩니다.

tools.py
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather in a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["city"],
            },
        },
    }
]

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto",
)
print(resp.choices[0].message.tool_calls)

비전

Claude는 3.5부터 멀티모달을 지원하며, 이미지를 전달할 때는 표준 OpenAI content: [{ type: 'text' }, { type: 'image_url' }] 배열을 사용합니다. image_url.url에는 https URL 또는 data: base64 URI를 사용할 수 있습니다.

vision.py
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url",
             "image_url": {"url": "https://example.com/cat.jpg"}},
        ],
    }],
)

네이티브 Anthropic SDK를 사용해야 하는 경우

일부 Anthropic 전용 기능은 OpenAI 형태로 표현할 수 없습니다. 특히 프롬프트 캐싱을 위한 cache_control 지시문과 확장 thinking 토큰이 그렇습니다. 둘 중 하나가 필요하면 SDK를 전환하되 동일한 키를 유지하세요. Kunavo는 네이티브 /v1/messages 엔드포인트도 제공하므로 Anthropic SDK도 base_url 한 줄만 변경하면 사용할 수 있습니다.

anthropic_native.py
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com",     # SDK appends /v1/messages
)

resp = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system="You are a senior platform engineer.",
    messages=[{"role": "user", "content": "What is a hot standby?"}],
)
print(resp.content[0].text)

전달 가능한 매개변수 전체 목록은 네이티브 Messages API 문서를, 반복 프롬프트의 입력 비용을 최대 90% 절감하는 프롬프트 캐싱 방법은 /docs/caching을 참조하세요.

프롬프트 캐싱 자체는 SDK 전환을 필요로 하지 않습니다. 프롬프트가 길면 Kunavo가 OpenAI 형태의 경로에서 캐시 중단점을 대신 설정합니다. 설정 위치는 시스템 프롬프트, 도구 정의, 그리고 어시스턴트 턴이 이미 포함된 대화의 마지막 메시지입니다. 시스템 메시지, 사용자 메시지 또는 도구 정의에 직접 넣은 cache_control은 Claude에 전달됩니다.

포기하는 것과 얻는 것

OpenAI 형태의 경로는 네이티브 프로토콜이 아니라 변환 계층입니다. 두 가지 작은 요소는 경계를 넘지 못합니다:

  • 사고 제어 — thinking 및 reasoning_effort는 이 경로에서 Claude에 전달되지 않습니다. 확장 사고를 켜거나 조정하려면 네이티브 Messages API를 사용하세요.
  • 사고 출력 — 모델이 사고를 수행해도 응답에는 그 내용이 포함되지 않으며, usage 객체에도 이를 따로 집계한 항목이 없습니다. 사고 토큰은 completion_tokens에 포함되어 집계됩니다.

얻게 되는 이점은 상당합니다. Claude, GPT, GPT-Image, Veo 및 나머지 카탈로그 전체에서 하나의 SDK를 사용할 수 있고, 모델에 따라 공식 제공업체 가격보다 저렴하며, 현지 통화로 Stripe 기반 결제를 이용할 수 있습니다. 모델이 조용히 바뀌는 일도 없습니다. 장애 조치는 제공업체만 변경하고 모델은 변경하지 않으며, 대시보드에는 모든 호출의 모델, 토큰 및 비용이 항목별로 표시됩니다.

2분이면 확인할 수 있습니다

kunavo.com/app/signup에서 가입하세요. $10 충전으로 수천 건의 Claude 호출을 사용할 수 있고, 사용한 만큼만 결제하며 잔액은 만료되지 않습니다. base_url를 입력하고 모델 ID를 Claude 슬러그로 바꾼 다음 기존 테스트 모음을 실행해 보세요. 무언가 원활하게 전환되지 않으면 contact@kunavo.com으로 이메일을 보내 주세요. 모든 메시지를 읽습니다.

관련 심층 분석