OpenAI-compatible과 Anthropic-compatible API: 무엇을 선택할까

API-compatible의 정확한 의미

compatible API는 익숙한 요청 형식을 받아 기존 SDK나 클라이언트가 해석할 수 있는 응답을 반환합니다. 일반적인 연동에서는 애플리케이션 코드 대부분을 유지하면서 Base URL, API Key, Model ID를 바꿉니다.

다만 이 용어에는 명확한 경계가 있습니다. provider가 기본 텍스트 생성을 지원하더라도 특정 parameter, hosted tool, audio, image endpoint 또는 정확한 오류 semantics까지 지원하지 않을 수 있습니다. model 필드를 제공하는 두 endpoint도 모델 목록을 표시하고 접근 권한을 부여하는 방식은 서로 다를 수 있습니다.

선택한 프로토콜로 실제 요청을 테스트하고 싶나요? 본인의 BetterToken 계정과 API Key를 만들고, quickstart를 열어 최소 테스트 한 건을 보내세요. BetterToken은 OpenAI-compatible과 Anthropic-compatible 인터페이스를 따로 제공합니다. 프로토콜, Base URL, API Key 유형, 현재 Model ID는 현재 API reference와 일치해야 합니다.

요청과 인증 방식의 차이

OpenAI-compatible 흐름에서는 보통 클라이언트가 Chat Completions용 messages 또는 Responses용 input을 구성합니다. 인증에는 일반적으로 Bearer token을 사용합니다.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages는 자체 메시지 구조, 별도의 system 필드, 필수 output limit, protocol version을 사용합니다. Anthropic 공식 API는 x-api-key와 anthropic-version 같은 header를 사용합니다.

x-api-key: YOUR_API_KEY
anthropic-version: CURRENT_SUPPORTED_VERSION
Content-Type: application/json

compatible gateway는 다른 인증 방식을 받을 수 있습니다. 호출할 endpoint의 문서에서 header를 가져오세요. 공식 API 예시는 프로토콜 형식을 설명할 뿐, provider의 integration guide를 대체하지 않습니다.

system instruction의 위치도 contract마다 다릅니다. 한 프로토콜에서는 messages 안에 두지만, 다른 프로토콜에서는 별도 필드로 보낼 수 있습니다. 기계적인 변환은 context 순서, cache prefix 또는 클라이언트 동작을 바꿀 수 있습니다.

Chat Completions, Responses, Messages는 서로 다른 contract

OpenAI-compatible이라는 표현만으로 어떤 인터페이스가 구현되었는지 알 수는 없습니다. migration 전에 정확한 contract를 기록하세요.

• Chat Completions: messages 배열, choices 아래의 응답, delta 아래의 streamed fragment를 사용합니다.
• Responses API: input item, typed output item, 별도의 response lifecycle event를 사용합니다.
• Anthropic Messages: messages, 별도 system 필드, content block, 고유한 stream event를 사용합니다.

라이브러리가 Responses를 요구한다면 /chat/completions만 구현된 endpoint로는 부족합니다. Claude Code가 Anthropic Messages를 요구한다면 adapter 없이 OpenAI-compatible endpoint를 사용할 수 없습니다. Base URL만 바꿔도 되는 경우는 클라이언트와 서버가 같은 contract를 구현했을 때뿐입니다.

Streaming과 완료 처리의 차이

세 인터페이스 모두 데이터를 stream할 수 있지만 event 이름과 순서는 서로 다릅니다.

Responses API는 response 생성, output text fragment, terminal state를 위한 typed Server-Sent Events를 전송합니다. 클라이언트는 completion event를 기다리거나 failed 또는 incomplete response를 처리해야 합니다.

Anthropic Messages는 message_start, content-block event, message_delta, message_stop을 보냅니다. 최초 HTTP response가 성공한 뒤에도 이미 열린 stream 안에서 오류가 도착할 수 있습니다.

Chat Completions에서는 보통 클라이언트가 choices[0].delta를 누적하고 해당 endpoint의 contract에 따라 종료를 감지합니다. 하나의 marker만 기다리는 코드를 검증 없이 Responses나 Messages로 옮길 수는 없습니다.

최소 handler는 네 가지 상태를 유지합니다.

created -> receiving -> completed
                   \-> failed
                   \-> disconnected

disconnected는 completed가 아닙니다. 일부 response를 받은 뒤 연결이 끊기면 이미 수신한 event를 보존하고 retry가 안전한지 판단하세요.

Tool use와 structured output

tools와 tool_calls처럼 비슷한 필드 이름은 실제보다 더 높은 호환성을 암시할 수 있습니다. 최소한 다음 항목을 테스트하세요.

• JSON Schema와 지원되는 type restriction
• parallel tool call
• tool result를 모델로 돌려보내는 방식
• streamed argument 조립
• 유효하지 않은 JSON에서의 동작
• strict structured output과 schema refusal

adapter는 필드 이름만 바꾸지 말고 호출의 의미를 보존해야 합니다. 특히 side effect가 있는 tool에서는 중요합니다. 같은 tool call을 반복하면 메시지를 한 번 더 보내거나 레코드를 새로 만들거나 작업을 두 번 실행할 수 있습니다.

HTTP status만으로 오류를 매핑하지 않기

401, 403, 404, 429, 5xx는 유용한 1차 분류이지만 provider마다 오류 body와 header가 다릅니다. 다음 정보를 보존하세요.

• HTTP status
• provider error type과 code
• 비밀 정보가 없는 짧은 message
• request ID
• retry 관련 header
• endpoint, 프로토콜, Model ID

API Key, 전체 prompt 또는 민감한 response를 로그에 남기지 마세요. gateway가 오류를 normalize한다면 원래 provider code를 안전한 내부 필드에 보존하세요. 그러지 않으면 model not found, access 부족, endpoint mismatch가 모두 도움이 되지 않는 400 하나로 합쳐질 수 있습니다.

프로토콜 선택 방법

완성형 AI 도구

먼저 도구 문서를 읽으세요. OpenAI Base URL을 요구하고 Chat Completions 또는 Responses를 사용한다면 해당 OpenAI-compatible endpoint를 선택합니다. ANTHROPIC_BASE_URL을 읽고 Messages를 요구한다면 Anthropic-compatible endpoint를 사용합니다.

모델 이름으로 프로토콜을 선택하지 마세요. gateway를 통해 모델을 사용할 수 있더라도 클라이언트는 여전히 특정 요청 형식을 요구할 수 있습니다.

자체 애플리케이션

결정은 이미 사용하는 SDK와 기능에 따라 달라집니다. 새 애플리케이션이라면 streaming, tools, structured output, vision, token usage, batch operation 또는 다른 endpoint 등 필요한 capability를 먼저 나열하세요. 각 항목을 provider 공식 문서에서 검증해야 합니다.

Provider migration

변경되는 코드 줄 수가 아니라 contract의 표면적을 평가하세요. 기본 chat은 새 설정값 세 개만 필요할 수 있습니다. tools, 긴 history, cache, streaming을 사용하는 agent 애플리케이션은 일반적으로 adapter와 integration test가 필요합니다.

프로덕션 트래픽 이전 전 테스트

1. SDK, endpoint, API version을 기록합니다.
2. 현재 catalog에서 정확한 Model ID를 복사합니다.
3. tools나 streaming 없이 짧은 요청을 보냅니다.
4. terminal event까지 기본 응답을 stream합니다.
5. 외부 side effect가 없는 안전한 tool call을 실행합니다.
6. 의도적으로 잘못된 Model ID를 사용해 controlled error를 만듭니다.
7. usage, status, request ID를 Dashboard와 대조합니다.
8. timeout 처리와 횟수가 제한된 retry를 테스트합니다.

그 후에만 실제 트래픽을 옮기세요. BetterToken에서는 API reference부터 확인하고, 하나의 프로토콜을 선택한 다음 agent tools를 활성화하기 전에 최소 요청을 검증하세요.

FAQ

OpenAI-compatible API는 OpenAI API를 완전히 재현하나요?

아닙니다. 이 용어는 특정 인터페이스와의 호환성을 뜻합니다. 모델, parameter, tools, streaming, 오류, 추가 endpoint는 각각 별도로 검증해야 합니다.

OpenAI SDK로 Anthropic-compatible endpoint를 호출할 수 있나요?

SDK가 OpenAI contract를 전송한다면 직접 호출할 수 없습니다. Anthropic Messages를 지원하는 클라이언트나 messages, streaming, tool use를 올바르게 변환하는 adapter를 사용하세요.

Base URL만 바꾸면 충분한가요?

이미 호환되는 클라이언트에서 짧은 텍스트 요청을 보낼 때는 가능할 수 있습니다. 프로덕션 migration에서는 Model ID, 인증, streaming, tools, 오류, usage를 계속 검증해야 합니다.

Claude Code에는 어떤 프로토콜이 필요한가요?

Claude Code는 일반적으로 Anthropic-compatible 인터페이스를 사용합니다. 정확한 변수, Base URL, 모델 설정은 현재 BetterToken guide에서 확인하세요.