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 형식은 실시간 모델 및 가격 카탈로그를 기준으로 확인하세요.

전환 전에 현재 구성을 정리하기

애플리케이션 코드를 바꾸기 전에 다음을 먼저 준비합니다.

  1. 개인용 또는 다른 연동의 키를 재사용하지 말고 API 키에서 전용 키를 만듭니다.
  2. 대상 모델에 접근할 수 있는 기본 모델 그룹을 선택합니다.
  3. 동일 모델을 지원하고 비용·안정성 정책에도 맞는 그룹만 폴백 순서에 추가합니다.
  4. 현재 엔드포인트, 정확한 모델 ID, 스트리밍 설정, 도구 사용 방식을 기록해 전환 전후를 비교합니다.

Modelflare OpenAI 호환 API의 표준 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": "현재 사용 중인 모델 이름으로 답해 주세요."}
    ],
    "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": "현재 사용 중인 모델 이름으로 답해 주세요.",
    "stream": false
  }'

카탈로그에 표시된 모델 ID를 정확히 사용하세요. model_not_found는 대개 키나 그룹에 모델 접근 권한이 없다는 뜻이며, 대소문자만 바꿔서는 해결되지 않습니다.

스트리밍은 별도로 검증하기

애플리케이션이 스트리밍에 의존한다면 비스트리밍 요청 성공만으로는 충분하지 않습니다. "stream": true로 다시 호출해 이벤트가 순차적으로 도착하는지, 클라이언트가 전체 응답을 버퍼링한 뒤 한 번에 보여 주지는 않는지 확인하세요.

스트리밍이 느릴 때는 다음 구간을 나눠 봅니다.

  • 인증과 라우팅에 걸린 시간
  • 업스트림 응답 헤더가 올 때까지의 시간
  • 첫 유효 텍스트, 추론, 도구 이벤트가 올 때까지의 시간
  • 화면 출력이 시작된 뒤의 생성 속도

Modelflare 사용 로그는 요청별 시간 지표를 남기지만 프롬프트, 응답 본문, 원본 요청 바디, API 키, 이메일, 평문 IP 주소는 저장하지 않습니다.

프로덕션 전환 체크리스트

  • API 키를 시크릿 저장소나 환경 변수에 보관합니다.
  • Base URL을 https://modelflare.dev/v1로 고정합니다.
  • 선택한 엔드포인트를 명시적으로 지원하는 모델을 사용합니다.
  • 스트리밍과 비스트리밍을 각각 테스트합니다.
  • 사용 중인 도구, 구조화 출력, 추론 옵션, 멀티모달 입력을 각각 검증합니다.
  • 의미가 있는 0과 false 값을 누락하지 않습니다.
  • 짧은 상태 확인 요청이 아니라 실제 워크로드에 맞춰 타임아웃을 설정합니다.
  • 전환 뒤 상태, 지연 시간, 토큰, 실제 선택 그룹, 비용을 사용 로그에서 확인합니다.

프로토콜 경계를 검증하면 클라이언트는 기존 요청 생명주기를 대부분 유지할 수 있습니다. 같은 엔드포인트 뒤에서 Modelflare가 모델 접근, 라우팅 정책, 요청별 관측 정보를 관리합니다.