API 키 10개의 지옥에서 벗어나는 법 — Gateway API

TL;DR

LLM 서비스를 만들다 보면 OpenAI, Anthropic, Google, xAI 등 여러 프로바이더의 API를 동시에 써야 할 때가 와요. API 키 관리, SDK 버전, 인증 방식이 전부 달라서 머리가 아프죠. FactChat Gateway API는 하나의 엔드포인트로 모든 LLM을 호출할 수 있게 만든 통합 프록시 서비스예요.

API 키만 10개, 이거 정상인가요

LLM을 하나만 쓰는 프로젝트는 거의 없어요.

GPT-5로 메인 추론을 하고, Claude로 코드 생성을 돌리고, Gemini로 멀티모달 처리를 하고, Perplexity로 검색 증강을 붙이고. 모델마다 잘하는 게 다르니까 자연스럽게 멀티 프로바이더 구조가 되는 거예요.

근데 이게 쌓이면 슬슬 이런 상황이 돼요:

.env 파일에 API 키가 10개 넘게 쌓여 있어요
OpenAI는 Authorization: Bearer, Anthropic은 x-api-key 헤더를 써요
SDK 버전이 서로 다르고, 에러 응답 형식도 전부 달라요
결제가 프로바이더별로 흩어져 있어서 이번 달 총비용을 모아보려면 대시보드를 5개 열어야 해요

처음엔 "그냥 wrapper 함수 하나 만들면 되지"라고 생각했어요. 근데 프로바이더가 3개를 넘는 순간, 그 wrapper가 프로젝트에서 제일 복잡한 코드가 되어 있더라고요.

Gateway API란

한 줄로 요약하면 이거예요: API 키 하나, base URL 하나로 모든 LLM 모델을 호출할 수 있는 통합 프록시.

FactChat Gateway API는 여러분의 애플리케이션과 LLM 프로바이더 사이에 위치해요. 기존 코드에서 base_url과 api_key만 바꾸면, 나머지는 Gateway가 알아서 처리해줘요.

12개 이상의 LLM 프로바이더를 지원해요 — OpenAI, Anthropic, Google Gemini, DeepSeek, xAI(Grok), Perplexity, Together AI, Fireworks AI, DeepInfra, Upstage, Friendli, 그리고 마인드로직 자체 모델까지
기존에 쓰던 OpenAI SDK나 Anthropic SDK를 그대로 사용할 수 있어요
Chat completions뿐 아니라 TTS, 이미지 생성, 영상 생성까지 하나의 엔드포인트로 가능해요
크레딧 기반 과금, 사용량 추적, 모델별 접근 제어까지 내장돼 있어요

그러니까 코드를 바꾸는 게 아니라, 가리키는 곳만 바꾸는 거예요.

어떻게 동작하나요

Gateway는 두 가지 포맷을 지원해요:

OpenAI Chat Completions 호환

https://factchat-cloud.mindlogic.ai/v1/gateway

OpenAI의 Chat Completions API 형식 그대로 요청을 보내면 돼요. OpenAI 모델뿐 아니라 다른 프로바이더의 모델도 model 파라미터만 바꿔서 호출할 수 있어요.

Anthropic Messages 호환

https://factchat-cloud.mindlogic.ai/v1/gateway/claude

Anthropic의 Messages API 형식을 선호한다면 이 엔드포인트를 쓰면 돼요. Claude 모델은 물론이고, 다른 모델도 Anthropic 형식으로 호출할 수 있어요.

OpenAI Responses API

https://factchat-cloud.mindlogic.ai/v1/gateway

OpenAI의 최신 Responses API도 지원해요. 비동기 폴링 방식으로 동작하고, 작업 취소도 가능해요.

지원 범위

기능	엔드포인트	설명
Chat Completions	`/chat/completions/`	텍스트 생성, 스트리밍, function calling, reasoning
Anthropic Messages	`/claude/v1/messages/`	Extended thinking, prompt caching, vision
Responses API	`/responses/`	비동기 폴링, 작업 취소
모델 목록	`/models/`	접근 가능한 모델 조회
TTS	`/audio/speech/`	Google Gemini 기반 음성 합성
이미지 생성	`/images/generate/`	동기(Google, OpenAI) + 비동기(Fal, Replicate)
영상 생성	`/video/generation/`	Google Veo, Fal Kling 등

인증은 Authorization: Bearer {API_KEY} 또는 x-api-key: {API_KEY} 둘 다 지원해요. 기존에 어떤 방식을 쓰고 있었든 바꿀 필요 없어요.

기존 코드에서 바꿀 것

진짜 거의 안 바꿔도 돼요. 코드로 보는 게 빨라요.

Python (OpenAI SDK)

Before:

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key"
)

response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "안녕하세요"}]
)

After:

from openai import OpenAI

client = OpenAI(
    base_url="https://factchat-cloud.mindlogic.ai/v1/gateway",
    api_key="your-gateway-api-key"
)

response = client.chat.completions.create(
    model="gpt-5",  # 또는 claude-opus-4-6, gemini-3.1-pro 등
    messages=[{"role": "user", "content": "안녕하세요"}]
)

바뀐 건 base_url과 api_key 딱 두 줄이에요. 나머지 코드는 한 글자도 안 건드려요.

Python (Anthropic SDK)

import anthropic

client = anthropic.Anthropic(
    base_url="https://factchat-cloud.mindlogic.ai/v1/gateway/claude",
    api_key="your-gateway-api-key"
)

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕하세요"}]
)

cURL

curl -X POST https://factchat-cloud.mindlogic.ai/v1/gateway/chat/completions \
  -H "Authorization: Bearer your-gateway-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

핵심은 이거예요: 기존 SDK를 버리지 않아도 된다는 것. OpenAI SDK든 Anthropic SDK든, base_url만 Gateway로 바꾸면 그대로 동작해요.

SDK뿐만 아니라, 도구도 연결돼요

OpenAI SDK 호환이라는 건 단순히 Python 코드만 해당되는 게 아니에요. OpenAI 호환 API를 지원하는 모든 도구와 바로 연결된다는 뜻이에요.

Claude Code — base_url만 Gateway로 설정하면 Claude Code에서 Gateway를 통해 다양한 모델을 쓸 수 있어요
OpenClaw — OpenAI 호환 엔드포인트를 지원하니까 Gateway와 바로 연동돼요
OpenCode — 터미널 기반 AI 코딩 도구도 마찬가지로 base_url 변경만으로 연결
Cursor / Continue / Cline — IDE 기반 AI 코딩 도구들도 OpenAI 호환 API 설정에 Gateway URL을 넣으면 끝
LangChain / LlamaIndex — 프레임워크에서 OpenAI 클라이언트를 쓰는 부분에 Gateway를 끼우면, 프로바이더 전환이 설정 한 줄로 해결돼요

결국 OpenAI SDK 호환 = 생태계 전체와 호환이에요. 새로운 도구가 나와도 OpenAI API를 지원하면 Gateway에 바로 연결할 수 있어요.

왜 필요한가요

"그냥 프로바이더별로 따로 호출하면 안 되나요?"라는 질문이 나올 수 있어요. 물론 되죠. 근데 프로젝트 규모가 커지면 이런 것들이 하나씩 발목을 잡아요.

프로바이더 전환이 코드 변경 없이 가능해요

새로운 모델이 나왔을 때, 코드를 배포하지 않고 model 파라미터만 바꿔서 테스트해볼 수 있어요. "GPT-5 대신 Claude 써볼까?"가 설정 한 줄로 끝나는 거예요.

비용 추적이 한곳에서 돼요

프로바이더 5곳의 대시보드를 각각 열어서 비용을 합산하는 대신, Gateway 대시보드 하나에서 전체 사용량과 비용을 확인할 수 있어요. 팀 단위로 사용량을 나눠서 보는 것도 가능해요.

에러 핸들링이 일관적이에요

프로바이더마다 다른 에러 코드, 다른 재시도 로직을 짤 필요가 없어요. Gateway가 일관된 형식으로 에러를 반환해주니까, 에러 핸들링 코드가 훨씬 깔끔해져요.

Rate limiting

Gateway 자체적으로 분당 120건의 요청 제한이 있어요. Redis 기반으로 멤버별로 정확하게 카운팅하고, 한도를 넘으면 429 응답과 함께 리셋 시간을 알려줘요. TTS 같은 무거운 작업은 분당 60건으로 별도 제한을 걸어뒀어요. 애플리케이션에서 직접 rate limiting 로직을 짤 필요가 없어요.

크레딧 기반 과금

요청 전에 예상 토큰 수를 계산해서 크레딧을 미리 예약하고, 응답이 끝나면 실제 사용량 기준으로 정산해요. 프롬프트 캐싱을 쓰면 캐시된 토큰에 대해 할인된 요금이 적용돼요. 모델별, 멤버별, 팀별로 사용량을 추적할 수 있어서, "이번 달 우리 팀이 GPT-5에 얼마 썼지?"가 바로 나와요.

모델 접근 제어

모든 모델이 모든 사용자에게 열려 있는 건 아니에요. 멤버 그룹별로 접근 가능한 모델을 설정할 수 있어요. 비싼 모델은 특정 그룹에만 허용하고, 기본 모델은 전체 공개하는 식으로 유연하게 관리할 수 있어요.

마무리

결국 Gateway API가 해결하는 문제는 명확해요. LLM 프로바이더가 늘어날수록 복잡해지는 통합 코드를, 인프라 레벨에서 한 번에 정리해주는 것.

이미 OpenAI SDK나 Anthropic SDK를 쓰고 있다면, 마이그레이션 비용은 거의 없어요. base_url과 api_key 두 줄만 바꾸면 되니까요.

더 자세한 내용은 Gateway API 문서에서 확인할 수 있어요. 지원하는 모델 목록, 상세 API 스펙, 요금 정책까지 다 정리되어 있어요.

FactChat Gateway를 직접 써보고 싶다면 문의해 주세요. 같이 테스트해봐요.