OpenAI 호환 API 가이드: Base URL만 바꾸기
OpenAI 호환성이 실제로 다루는 범위, 기존 클라이언트를 Modelflare로 옮기는 방법, 프로덕션 트래픽을 보내기 전에 확인할 경계를 설명합니다.

OpenAI 호환 API를 사용하면 기존 클라이언트의 익숙한 인증 헤더, JSON 요청 형식, 스트리밍 방식을 그대로 유지하면서 트래픽만 다른 게이트웨이로 보낼 수 있습니다. 변경 작업은 Base URL과 API 키를 바꾸는 정도로 끝날 수도 있습니다. 하지만 호환성은 어디까지나 프로토콜 계약이며, 모든 모델이 모든 엔드포인트나 제공업체별 필드를 지원한다는 약속은 아닙니다.
이 가이드는 이미 OpenAI 방식의 API를 사용하는 애플리케이션, 스크립트, AI 도구를 안전하게 마이그레이션하는 방법을 설명합니다.
OpenAI 호환성이 실제로 다루는 범위
계약 중 가장 폭넓게 재사용할 수 있는 부분은 다음과 같습니다.
- Authorization 헤더를 통한 Bearer 토큰 인증
- 버전이 지정된 /v1 엔드포인트의 JSON 요청과 응답
- /v1/models, /v1/chat/completions, /v1/responses 같은 공통 엔드포인트
- 지원되는 스트리밍 요청에서 사용하는 Server-Sent Events
- 선택한 프로토콜이 지원하는 경우 model, messages, input, stream 같은 익숙한 요청 필드와 도구 정의
호환된다고 해서 하나의 모델을 Chat Completions와 Responses 사이에서 자유롭게 옮길 수 있다는 뜻은 아닙니다. 어떤 모델은 검증된 프로토콜 하나로만 제공될 수 있습니다. 또한 제공업체별 추론, 검색, 멀티모달 필드는 게이트웨이에서 변환하지 않고 원본 그대로 전달해야 할 수도 있습니다.
사용하려는 모델, 그룹, API 형식은 실시간 모델 및 요금 카탈로그를 기준으로 확인하세요.
마이그레이션 준비하기
애플리케이션 코드를 변경하기 전에 다음을 준비하세요.
- 개인 키나 관련 없는 연동의 키를 재사용하지 말고 API 키에서 전용 키를 생성합니다.
- 사용하려는 모델에 액세스할 수 있는 기본 모델 그룹을 선택합니다.
- 폴백 그룹은 같은 모델을 지원하고 동일한 비용·안정성 정책에 맞는 경우에만 순서대로 추가합니다.
- 변경 전후의 동작을 비교할 수 있도록 현재 엔드포인트, 모델 ID, 스트리밍 설정, 도구 사용 방식을 기록합니다.
Modelflare의 표준 OpenAI 호환 Base URL은 다음과 같습니다.
https://modelflare.dev/v1
대부분의 SDK는 Base URL이 /v1로 끝난다고 가정하고 /chat/completions 또는 /responses를 직접 덧붙입니다. 엔드포인트 경로를 한 번 더 붙이기 전에 클라이언트 문서를 확인하세요.
인증과 모델 액세스부터 확인하기
키는 소스 코드가 아니라 환경 변수에 저장하세요.
export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'
그런 다음 이 키로 사용 가능한 모델 목록을 조회할 수 있는지 확인합니다.
curl -sS https://modelflare.dev/v1/models \
-H "Authorization: Bearer $MODELFLARE_API_KEY"
성공 응답은 호스트 이름, TLS 경로, 키가 유효하다는 것을 보여 줍니다. 하지만 반환된 모든 모델에서 특정 요청 형식이 유효하다는 것까지 증명하지는 않으므로, 다음 확인은 실제로 사용할 엔드포인트로 진행해야 합니다.
사용할 프로토콜로 요청 하나 보내기
Chat Completions 형식과 호환된다고 표시된 모델이라면 다음과 같이 요청합니다.
curl -sS https://modelflare.dev/v1/chat/completions \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CHAT_MODEL",
"messages": [
{"role": "user", "content": "Reply with the active model name."}
],
"stream": false
}'
Responses와 호환되는 코딩 모델이라면 다음과 같이 요청합니다.
curl -sS https://modelflare.dev/v1/responses \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"input": "Reply with the active model name.",
"stream": false
}'
실시간 카탈로그에 표시된 정확한 모델 ID를 사용하세요. model_not_found 결과는 대개 선택한 키나 그룹이 해당 모델에 액세스할 수 없다는 뜻이며, 대소문자를 바꾼다고 해결되지 않습니다.
스트리밍은 따로 검증하기
스트리밍에 의존하는 애플리케이션이라면 비스트리밍 요청이 성공한 것만으로는 충분하지 않습니다. "stream": true로 같은 요청을 다시 보내 이벤트가 점진적으로 도착하는지 확인하고, 클라이언트가 전체 응답을 버퍼링한 뒤에야 렌더링하지 않는지도 확인하세요.
스트림이 느린 원인을 진단할 때는 다음 구간을 나눠서 보세요.
- 인증과 경로 선택에 걸린 시간
- 공급사 응답 헤더가 도착할 때까지의 시간
- 첫 유효 콘텐츠 또는 도구 델타가 도착할 때까지의 시간
- 화면 출력이 시작된 뒤의 생성 처리량
Modelflare 사용 로그는 이를 위해 요청 단위의 시간 메타데이터를 보관하지만 프롬프트, 응답 텍스트, 원본 요청 본문, API 키, 이메일, 평문 IP 주소는 저장하지 않습니다.
프로덕션 마이그레이션 체크리스트
- API 키를 시크릿 저장소나 환경 변수에 보관합니다.
- Base URL을 https://modelflare.dev/v1로 고정합니다.
- 선택한 엔드포인트를 명시적으로 지원하는 모델을 사용합니다.
- 비스트리밍 모드와 스트리밍 모드를 각각 테스트합니다.
- 애플리케이션에서 사용한다면 도구, 구조화된 출력, 추론 제어, 멀티모달 입력도 테스트합니다.
- 클라이언트 요청에서 의미가 있는 명시적인 0 또는 false 값을 그대로 유지합니다.
- 짧은 상태 확인용 프롬프트가 아니라 실제 워크로드에 맞춰 클라이언트 타임아웃을 설정합니다.
- 전환 후 사용 로그에서 상태, 지연 시간, 토큰 사용량, 선택된 그룹, 비용을 검토합니다.
프로토콜 경계를 검증하고 나면 클라이언트는 대개 기존 요청 생명주기를 그대로 유지할 수 있습니다. 호환 엔드포인트 뒤에서는 Modelflare가 모델 액세스, 라우팅 정책, 요청별 가시성을 제공합니다.
이 엔드포인트 뒤에서 동작하는 운영 계층은 AI API 게이트웨이란?에서 자세히 설명합니다. 클라이언트가 두 가지 이상의 OpenAI 형식을 사용할 수 있다면 경로를 바꾸기 전에 Responses API와 Chat Completions 비교를 먼저 확인하세요.