--- title: OpenAI SDK 호환성 url: https://platform.claude.com/docs/ko/cli-sdks-libraries/libraries/openai-sdk description: Anthropic은 OpenAI SDK를 사용하여 Claude API를 테스트할 수 있도록 하는 호환성 레이어를 제공합니다. 몇 가지 코드 변경만으로 Anthropic 모델의 기능을 빠르게 평가할 수 있습니다. --- 이 호환성 레이어는 주로 모델 기능을 테스트하고 비교하기 위한 것이며, 대부분의 사용 사례에서 장기적이거나 프로덕션에 적합한 솔루션으로 간주되지 않습니다. 완전한 기능을 유지하고 호환성을 깨는 변경이 없도록 할 예정이지만, 우선순위는 [Claude API](https://platform.claude.com/docs/ko/api/overview)의 안정성과 효과성에 있습니다. 알려진 호환성 제한 사항에 대한 자세한 내용은 [중요한 OpenAI 호환성 제한 사항](https://platform.claude.com/docs/ko/cli-sdks-libraries/libraries/openai-sdk#important-openai-compatibility-limitations)을 참조하세요. OpenAI SDK 호환성 기능에 문제가 발생하면 이 [호환성 피드백 양식](https://forms.gle/oQV4McQNiuuNbz9n8)을 통해 피드백을 공유해 주세요. 최상의 경험과 Claude API의 전체 기능 세트([PDF 처리](https://platform.claude.com/docs/ko/build-with-claude/pdf-support), [인용](https://platform.claude.com/docs/ko/build-with-claude/citations), [사고](https://platform.claude.com/docs/ko/build-with-claude/thinking), ["prompt caching"(프롬프트 캐싱)](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching))에 액세스하려면 네이티브 [Claude API](https://platform.claude.com/docs/ko/api/overview)를 사용하세요. ## OpenAI SDK 시작하기 OpenAI SDK 호환성 기능을 사용하려면 다음을 수행해야 합니다: 1. 공식 OpenAI SDK를 사용합니다 2. 다음을 변경합니다 * 기본 URL이 Claude API를 가리키도록 업데이트합니다 * API 키를 [Claude API 키](https://platform.claude.com/settings/keys)로 교체합니다 * 키가 여러 워크스페이스에 액세스할 수 있는 [개인 또는 서비스 계정 키](https://platform.claude.com/docs/ko/manage-claude/authentication#key-types)인 경우, 모든 요청에 `anthropic-workspace-id` 헤더도 함께 전송합니다(예: Python SDK의 `default_headers` 또는 TypeScript의 `defaultHeaders`). [워크스페이스 선택](https://platform.claude.com/docs/ko/manage-claude/authentication#select-a-workspace)을 참조하세요 * [Claude 모델](https://platform.claude.com/docs/ko/models/overview)을 사용하도록 모델 이름을 업데이트합니다 3. 지원되는 기능에 대해서는 다음 섹션을 검토합니다 ### 빠른 시작 예제 ```python Python 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) ``` ```typescript TypeScript import OpenAI from "openai"; const openai = new OpenAI({ apiKey: process.env.ANTHROPIC_API_KEY, // Your Claude API key baseURL: "https://api.anthropic.com/v1/" // Claude API endpoint }); const response = await openai.chat.completions.create({ messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Who are you?" } ], model: "claude-opus-5-5" // Claude model name }); console.log(response.choices[0].message.content); ``` ```csharp C# using System.ClientModel; using OpenAI; using OpenAI.Chat; ChatClient chatClient = new( model: "claude-opus-5-5", // Claude model name credential: new ApiKeyCredential( Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")), // Your Claude API key options: new OpenAIClientOptions() { Endpoint = new Uri("https://api.anthropic.com/v1/") // the Claude API endpoint }); ChatCompletion completion = chatClient.CompleteChat( new SystemChatMessage("You are a helpful assistant."), new UserChatMessage("Who are you?")); Console.WriteLine(completion.Content[0].Text); ``` ```go Go package main import ( "context" "fmt" "os" "github.com/openai/openai-go/v3" "github.com/openai/openai-go/v3/option" ) func main() { client := openai.NewClient( option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")), // Your Claude API key option.WithBaseURL("https://api.anthropic.com/v1/"), // the Claude API endpoint ) response, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{ Model: "claude-opus-5-5", // Claude model name Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage("You are a helpful assistant."), openai.UserMessage("Who are you?"), }, }) if err != nil { panic(err) } fmt.Println(response.Choices[0].Message.Content) } ``` ```java Java import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public class QuickStart { public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.builder() .apiKey(System.getenv("ANTHROPIC_API_KEY")) // Your Claude API key .baseUrl("https://api.anthropic.com/v1/") // the Claude API endpoint .build(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .model("claude-opus-5-5") // Claude model name .addSystemMessage("You are a helpful assistant.") .addUserMessage("Who are you?") .build(); ChatCompletion completion = client.chat().completions().create(params); System.out.println(completion.choices().get(0).message().content().orElse("")); } } ``` OpenAI에는 공식 PHP SDK가 없습니다. PHP에서 Claude를 사용하려면 대신 [PHP용 Claude SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/php)를 사용하세요. ```ruby Ruby require "openai" openai = OpenAI::Client.new( api_key: ENV["ANTHROPIC_API_KEY"], # Your Claude API key base_url: "https://api.anthropic.com/v1/" # the Claude API endpoint ) response = openai.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?"} ] ) puts response.choices.first.message.content ``` ## 중요한 OpenAI 호환성 제한 사항 ### API 동작 OpenAI 사용과 비교했을 때 가장 큰 차이점은 다음과 같습니다: * 함수 호출의 `strict` 매개변수는 무시되며, 이는 "tool use"(도구 사용) JSON이 제공된 스키마를 따른다고 보장되지 않음을 의미합니다. 스키마 준수를 보장하려면 네이티브 [Claude API의 구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 사용하세요. * 오디오 입력은 지원되지 않으며, 무시되고 입력에서 제거됩니다 * 프롬프트 캐싱은 지원되지 않지만, [Anthropic SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)에서는 지원됩니다 * 시스템/개발자 메시지는 대화의 어느 위치에 있든 최상위 `system` 필드로 끌어올려져(hoisted) 연결됩니다. 대화 도중에 시스템 지침을 추가하려면 네이티브 Claude API의 [대화 중간 시스템 메시지](https://platform.claude.com/docs/ko/build-with-claude/mid-conversation-system-messages)를 사용하세요. 지원되지 않는 대부분의 필드는 오류를 발생시키지 않고 조용히 무시됩니다. 이러한 내용은 모두 다음 섹션에 문서화되어 있습니다. ### 출력 품질 고려 사항 프롬프트를 많이 조정해 왔다면, 해당 프롬프트는 OpenAI에 특화되어 잘 튜닝되어 있을 가능성이 높습니다. [프롬프팅 모범 사례 가이드](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/claude-prompting-best-practices)를 사용하여 Claude에 맞게 재작업하는 것을 고려하세요. ### 시스템 / 개발자 메시지 끌어올리기 OpenAI SDK에 대한 대부분의 입력은 Anthropic의 API 매개변수에 명확하게 직접 매핑되지만, 한 가지 뚜렷한 차이점은 시스템 / 개발자 프롬프트의 처리 방식입니다. OpenAI에서는 이 두 프롬프트를 채팅 대화 전체에 걸쳐 배치할 수 있습니다. 호환성 레이어는 모든 시스템/개발자 메시지를 가져와 그 사이에 단일 줄바꿈(`\n`)을 넣어 하나로 연결합니다. 그런 다음 이 전체 문자열이 모든 메시지보다 앞서 최상위 `system` 필드로 제공됩니다. ### 사고 지원 `thinking` 매개변수를 추가하여 [사고](https://platform.claude.com/docs/ko/build-with-claude/thinking)를 활성화할 수 있습니다. 현재 모델에서 사고는 적응형(adaptive)으로, Claude가 언제 얼마나 깊이 사고할지 결정하며, Claude 5 모델에서는 기본적으로 활성화되어 있습니다. 수동으로 구성하는 확장 사고는 레거시 모드입니다. 사고는 복잡한 작업에 대한 Claude의 추론을 향상시키지만, OpenAI SDK는 Claude의 사고 내용을 반환하지 않습니다. [요약된 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking#summarized-thinking)를 포함한 전체 사고 기능을 사용하려면 네이티브 Claude API를 사용하세요. ```python Python 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}}, ) ``` ```typescript TypeScript const response = await openai.chat.completions.create({ messages: [{ role: "user", content: "Who are you?" }], model: "claude-sonnet-4-6", // @ts-expect-error thinking: { type: "enabled", budget_tokens: 2000 } }); ``` ```csharp C# // .NET SDK에는 Python과 같은 extra_body 매개변수가 없으므로, 이 예제에서는 // SDK에 문서화된 프로토콜 메서드(원시 JSON 요청 본문)를 사용하여 // thinking 매개변수를 전송합니다. BinaryData input = BinaryData.FromString(""" { "model": "claude-sonnet-4-6", "messages": [{ "role": "user", "content": "Who are you?" }], "thinking": { "type": "enabled", "budget_tokens": 2000 } } """); using BinaryContent content = BinaryContent.Create(input); ClientResult result = chatClient.CompleteChat(content); ``` ```go Go response, err := client.Chat.Completions.New( context.Background(), openai.ChatCompletionNewParams{ Model: "claude-sonnet-4-6", Messages: []openai.ChatCompletionMessageParamUnion{ openai.UserMessage("Who are you?"), }, }, option.WithJSONSet("thinking", map[string]any{"type": "enabled", "budget_tokens": 2000}), ) ``` ```java Java ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .model("claude-sonnet-4-6") .addUserMessage("Who are you?") .putAdditionalBodyProperty("thinking", JsonValue.from(Map.of("type", "enabled", "budget_tokens", 2000))) .build(); ChatCompletion completion = client.chat().completions().create(params); ``` OpenAI에는 공식 PHP SDK가 없습니다. PHP에서 Claude를 사용하려면 대신 [PHP용 Claude SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/sdks/php)를 사용하세요. ```ruby Ruby response = openai.chat.completions.create( model: "claude-sonnet-4-6", messages: [{role: "user", content: "Who are you?"}], request_options: {extra_body: {thinking: {type: "enabled", budget_tokens: 2000}}} ) ``` ## 속도 제한 "Rate limit"(속도 제한)은 `/v1/messages` 엔드포인트에 대한 Anthropic의 [표준 제한](https://platform.claude.com/docs/ko/api/rate-limits)을 따릅니다. ## 상세한 OpenAI 호환 API 지원 ### 요청 필드 #### 단순 필드 | 필드 | 지원 상태 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | Claude 모델 이름 사용 | | `max_tokens` | 완전 지원 | | `max_completion_tokens` | 완전 지원 | | `stream` | 완전 지원 | | `stream_options` | 완전 지원 | | `top_p` | 모델에 그대로 전달됩니다. Claude 4.7 이상 모델과 Claude Mythos Preview는 기본값인 `0.99` 이외의 값에 대해 400 오류를 반환하므로 생략하세요. `temperature`와 `top_p`를 모두 설정한 요청도 400 오류를 반환합니다. [Messages API 사용하기](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages)를 참조하세요. | | `parallel_tool_calls` | 완전 지원 | | `stop` | 공백이 아닌 모든 중지 시퀀스가 작동함 | | `temperature` | 0에서 1 사이(포함). 1보다 큰 값은 1로 제한됩니다. Claude 4.7 이상 모델과 Claude Mythos Preview에서는 1 미만의 값이 400 오류를 반환하므로 생략하세요. [Messages API 사용하기](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages)를 참조하세요. | | `n` | 정확히 1이어야 함 | | `logprobs` | 무시됨 | | `metadata` | 무시됨 | | `response_format` | 무시됨. JSON 출력의 경우 네이티브 Claude API의 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 사용하세요 | | `prediction` | 무시됨 | | `presence_penalty` | 무시됨 | | `frequency_penalty` | 무시됨 | | `seed` | 무시됨 | | `service_tier` | 무시됨 | | `audio` | 무시됨 | | `logit_bias` | 무시됨 | | `store` | 무시됨 | | `user` | 무시됨 | | `modalities` | 무시됨 | | `top_logprobs` | 무시됨 | | `reasoning_effort` | 무시됨 | #### `tools` / `functions` 필드 `tools[n].function` 필드 | 필드 | 지원 상태 | | ------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `name` | 완전 지원 | | `description` | 완전 지원 | | `parameters` | 완전 지원 | | `strict` | 무시됨. 엄격한 스키마 검증을 위해서는 네이티브 Claude API의 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 사용하세요 | `functions[n]` 필드 OpenAI는 `functions` 필드를 지원 중단했으며 대신 `tools`를 사용할 것을 권장합니다. | 필드 | 지원 상태 | | ------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `name` | 완전 지원 | | `description` | 완전 지원 | | `parameters` | 완전 지원 | | `strict` | 무시됨. 엄격한 스키마 검증을 위해서는 네이티브 Claude API의 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)을 사용하세요 | #### `messages` 배열 필드 `messages[n].role == "developer"`에 대한 필드 개발자 메시지는 초기 시스템 메시지의 일부로 대화 시작 부분으로 끌어올려집니다 | 필드 | 지원 상태 | | --------- | -------------- | | `content` | 완전 지원, 단 끌어올려짐 | | `name` | 무시됨 | `messages[n].role == "system"`에 대한 필드 시스템 메시지는 초기 시스템 메시지의 일부로 대화 시작 부분으로 끌어올려집니다 | 필드 | 지원 상태 | | --------- | -------------- | | `content` | 완전 지원, 단 끌어올려짐 | | `name` | 무시됨 | `messages[n].role == "user"`에 대한 필드 | 필드 | 변형 | 하위 필드 | 지원 상태 | | --------- | -------------------------------- | -------- | ----- | | `content` | `string` | | 완전 지원 | | | `array`, `type == "text"` | | 완전 지원 | | | `array`, `type == "image_url"` | `url` | 완전 지원 | | | | `detail` | 무시됨 | | | `array`, `type == "input_audio"` | | 무시됨 | | | `array`, `type == "file"` | | 무시됨 | | `name` | | | 무시됨 | `messages[n].role == "assistant"`에 대한 필드 | 필드 | 변형 | 지원 상태 | | --------------- | ---------------------------- | ----- | | `content` | `string` | 완전 지원 | | | `array`, `type == "text"` | 완전 지원 | | | `array`, `type == "refusal"` | 무시됨 | | `tool_calls` | | 완전 지원 | | `function_call` | | 완전 지원 | | `audio` | | 무시됨 | | `refusal` | | 무시됨 | `messages[n].role == "tool"`에 대한 필드 | 필드 | 변형 | 지원 상태 | | -------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `content` | `string` | 완전 지원 | | | `array`, `type == "text"` | 완전 지원 | | `tool_call_id` | | 완전 지원 | | `tool_choice` | | 지원됨. `"required"` 및 이름이 지정된 함수 값은 도구 호출을 강제합니다. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1은 강제 도구 사용을 지원하지 않으며 오류를 반환하므로, 해당 모델에서는 `"auto"`를 사용하세요. [도구 사용 강제하기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools#forcing-tool-use)를 참조하세요. | | `name` | | 무시됨 | `messages[n].role == "function"`에 대한 필드 | 필드 | 변형 | 지원 상태 | | ------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `content` | `string` | 완전 지원 | | | `array`, `type == "text"` | 완전 지원 | | `tool_choice` | | 지원됨. `"required"` 및 이름이 지정된 함수 값은 도구 호출을 강제합니다. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1은 강제 도구 사용을 지원하지 않으며 오류를 반환하므로, 해당 모델에서는 `"auto"`를 사용하세요. [도구 사용 강제하기](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools#forcing-tool-use)를 참조하세요. | | `name` | | 무시됨 | ### 응답 필드 | 필드 | 지원 상태 | | --------------------------------- | --------- | | `id` | 완전 지원 | | `choices[]` | 길이가 항상 1임 | | `choices[].finish_reason` | 완전 지원 | | `choices[].index` | 완전 지원 | | `choices[].message.role` | 완전 지원 | | `choices[].message.content` | 완전 지원 | | `choices[].message.tool_calls` | 완전 지원 | | `object` | 완전 지원 | | `created` | 완전 지원 | | `model` | 완전 지원 | | `finish_reason` | 완전 지원 | | `content` | 완전 지원 | | `usage.completion_tokens` | 완전 지원 | | `usage.prompt_tokens` | 완전 지원 | | `usage.total_tokens` | 완전 지원 | | `usage.completion_tokens_details` | 항상 비어 있음 | | `usage.prompt_tokens_details` | 항상 비어 있음 | | `choices[].message.refusal` | 항상 비어 있음 | | `choices[].message.audio` | 항상 비어 있음 | | `logprobs` | 항상 비어 있음 | | `service_tier` | 항상 비어 있음 | | `system_fingerprint` | 항상 비어 있음 | ### 오류 메시지 호환성 호환성 레이어는 OpenAI API와 일관된 오류 형식을 유지합니다. 그러나 상세한 오류 메시지는 동일하지 않습니다. 오류 메시지는 로깅 및 디버깅 용도로만 사용하세요. ### 헤더 호환성 OpenAI SDK가 헤더를 자동으로 관리하지만, 헤더를 직접 다루어야 하는 개발자를 위해 Claude API가 지원하는 전체 헤더 목록은 다음과 같습니다. | 헤더 | 지원 상태 | | -------------------------------- | --------------- | | `x-ratelimit-limit-requests` | 완전 지원 | | `x-ratelimit-limit-tokens` | 완전 지원 | | `x-ratelimit-remaining-requests` | 완전 지원 | | `x-ratelimit-remaining-tokens` | 완전 지원 | | `x-ratelimit-reset-requests` | 완전 지원 | | `x-ratelimit-reset-tokens` | 완전 지원 | | `retry-after` | 완전 지원 | | `request-id` | 완전 지원 | | `openai-version` | 항상 `2020-10-01` | | `authorization` | 완전 지원 | | `openai-processing-ms` | 항상 비어 있음 |