OpenAI SDK 호환성

OpenAI SDK 시작하기

OpenAI SDK 호환성 기능을 사용하려면 다음을 수행해야 합니다:

1. 공식 OpenAI SDK를 사용합니다.
2. 다음 사항을 변경합니다:
   • base URL이 Claude API를 가리키도록 업데이트합니다.
   • API 키를 Claude Console의 Claude API 키로 교체합니다.
   • 키가 워크스페이스로 범위가 지정되지 않은 개인 또는 서비스 계정 키인 경우, 모든 요청에 anthropic-workspace-id 헤더도 함께 전송하세요(예: Python SDK의 default_headers 또는 TypeScript의 defaultHeaders). 워크스페이스 선택을 참조하세요.
   • 모델 이름을 Claude 모델을 사용하도록 업데이트합니다.
3. 지원되는 기능에 대해서는 다음 섹션을 검토하세요.

빠른 시작 예제

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),  # Your Claude API key
    base_url="https://api.anthropic.com/v1/",  # the Claude API endpoint
)

response = client.chat.completions.create(
    model="claude-opus-5-5",  # Claude model name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"},
    ],
)

print(response.choices[0].message.content)

중요한 OpenAI 호환성 제한 사항

API 동작

OpenAI 사용과 비교했을 때 가장 큰 차이점은 다음과 같습니다:

• 함수 호출(function calling)의 strict 매개변수는 무시되므로, 도구 사용 JSON이 제공된 스키마를 따른다는 보장이 없습니다. 스키마 준수를 보장하려면 네이티브 structured outputs(구조화된 출력)를 사용하는 Claude API를 사용하세요.
• 오디오 입력은 지원되지 않으며, 무시되고 입력에서 제거됩니다.
• 프롬프트 캐싱은 지원되지 않지만, Anthropic SDK에서는 지원됩니다.
• 시스템/개발자 메시지는 대화의 어느 위치에 있든 최상위 system 필드로 끌어올려져(hoisted) 연결됩니다. 대화 도중에 시스템 지침을 추가하려면 네이티브 Claude API의 대화 중간 시스템 메시지를 사용하세요.

지원되지 않는 대부분의 필드는 오류를 발생시키지 않고 조용히 무시됩니다. 이러한 내용은 모두 다음 섹션에 문서화되어 있습니다.

출력 품질 고려 사항

프롬프트를 광범위하게 조정했다면, 해당 프롬프트는 OpenAI에 특화되어 잘 튜닝되어 있을 가능성이 높습니다. 프롬프팅 모범 사례 가이드를 사용하여 Claude에 맞게 재작업하는 것을 고려하세요.

시스템 / 개발자 메시지 끌어올리기

OpenAI SDK에 대한 대부분의 입력은 Claude API 매개변수에 명확하게 직접 매핑되지만, 한 가지 뚜렷한 차이점은 시스템 / 개발자 프롬프트의 처리 방식입니다. OpenAI API에서는 이 두 프롬프트를 채팅 대화 전체에 걸쳐 배치할 수 있습니다. 호환성 레이어는 모든 시스템/개발자 메시지를 가져와 그 사이에 단일 줄바꿈(\n)을 넣어 연결합니다. 이렇게 완성된 전체 문자열은 모든 메시지보다 앞서 최상위 system 필드로 제공됩니다.

사고 지원

thinking 매개변수를 추가하여 사고를 활성화할 수 있습니다. 현재 모델에서 사고는 적응형(adaptive)으로, Claude가 언제 얼마나 깊이 사고할지 결정하며, Claude 5 모델에서는 기본적으로 활성화되어 있습니다. 수동으로 구성하는 확장 사고는 레거시 모드입니다. 사고는 복잡한 작업에 대한 Claude의 추론을 향상시키지만, OpenAI SDK는 Claude의 사고 내용을 반환하지 않습니다. 요약된 사고를 포함한 전체 사고 기능을 사용하려면 네이티브 Claude API를 사용하세요.

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Who are you?"}],
    extra_body={"thinking": {"type": "enabled", "budget_tokens": 2000}},
)

속도 제한

"Rate limit"(속도 제한)은 /v1/messages 엔드포인트에 대한 Anthropic의 표준 제한을 따릅니다.

상세한 OpenAI 호환 API 지원

요청 필드

단순 필드

tools / functions 필드

messages 배열 필드

응답 필드

오류 메시지 호환성

호환성 레이어는 OpenAI API와 일관된 오류 형식을 유지합니다. 그러나 상세한 오류 메시지는 동일하지 않습니다. 오류 메시지는 로깅 및 디버깅 용도로만 사용하세요.

헤더 호환성

OpenAI SDK가 헤더를 자동으로 관리하지만, 헤더를 직접 다뤄야 하는 개발자를 위해 Claude API에서 지원하는 전체 헤더 목록은 다음과 같습니다.