OpenAI SDK 호환성

OpenAI SDK 시작하기

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

1. 공식 OpenAI SDK를 사용합니다
2. 다음을 변경합니다
   • 기본 URL이 Claude API를 가리키도록 업데이트합니다
   • API 키를 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",  # 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 사용과 비교했을 때 가장 큰 차이점은 다음과 같습니다:

• 함수 호출의 strict 매개변수는 무시되며, 이는 "tool use"(도구 사용) JSON이 제공된 스키마를 따른다고 보장되지 않음을 의미합니다. 스키마 준수를 보장하려면 네이티브 Claude API의 구조화된 출력을 사용하세요.
• 오디오 입력은 지원되지 않으며, 무시되고 입력에서 제거됩니다
• 프롬프트 캐싱은 지원되지 않지만, Anthropic SDK에서는 지원됩니다
• Anthropic은 단일 초기 시스템 메시지만 지원하므로, 시스템/개발자 메시지는 대화의 시작 부분으로 끌어올려져 연결됩니다.

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

출력 품질 고려 사항

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

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

OpenAI SDK에 대한 대부분의 입력은 Anthropic의 API 매개변수에 명확하게 직접 매핑되지만, 한 가지 뚜렷한 차이점은 "system prompt"(시스템 프롬프트) / 개발자 프롬프트의 처리 방식입니다. OpenAI에서는 이 두 프롬프트를 채팅 대화 전반에 걸쳐 배치할 수 있습니다. Anthropic은 초기 시스템 메시지만 지원하므로, API는 모든 시스템/개발자 메시지를 가져와 사이에 단일 줄바꿈(\n)을 넣어 함께 연결합니다. 그런 다음 이 전체 문자열이 메시지 시작 부분에 단일 시스템 메시지로 제공됩니다.

사고 지원

thinking 매개변수를 추가하여 사고를 활성화할 수 있습니다. 현재 모델에서 사고는 적응형으로, Claude가 언제 얼마나 깊이 사고할지 결정하며, Claude 5 모델에서는 기본적으로 켜져 있습니다. 수동으로 구성하는 "extended thinking"(확장 사고)은 레거시 모드입니다. 사고는 복잡한 작업에 대한 Claude의 추론을 향상시키지만, OpenAI SDK는 Claude의 상세한 사고 과정을 반환하지 않습니다. 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가 지원하는 전체 헤더 목록은 다음과 같습니다.