FreeLLMAPI를 사용하여 약 8억 개의 무료 AI 토큰을 단일 OpenAI API로 통합하기

아무도 말하지 않는 문제
모든 주요 AI 연구소(AI lab)는 이제 무료 티어(free tier)를 제공합니다. Gemini, Groq, Mistral, Cerebras — 이들은 모두 한 달에 수백만 개의 토큰과 하루에 수천 건의 요청을 제공합니다. 서류상으로는 관대해 보입니다. 하지만 실제로 사용하다 보면 14개의 서로 다른 SDK, 14개의 속도 제한(rate limits), 그리고 요청이 조용히 실패할 수 있는 14곳의 지점을 관리해야 하는 상황에 처하게 됩니다. FreeLLMAPI는 바로 그 문제를 해결합니다.

작동 방식
이것은 14개 제공업체의 무료 티어를 단일 /v1/chat/completions 엔드포인트 뒤로 통합하는 셀프 호스팅 프록시(self-hosted proxy)이며, OpenAI SDK와 완전히 호환됩니다.

지원되는 제공업체:

제공업체	주요 모델
Google	Gemini 2.5 Pro / Flash
Groq	Llama 4, Qwen, Kimi
Cerebras	Llama 3.3, Qwen
SambaNova	Llama 3.3 70B
NVIDIA NIM	전체 카탈로그
Mistral	La Plateforme
OpenRouter	무료 티어 모델
GitHub Models	GPT-4o, Llama, Phi
Hugging Face Inference Providers	(제공 모델)
Cloudflare Workers AI	(제공 모델)
Zhipu	GLM-4 시리즈
Moonshot	Kimi
MiniMax	abab / hailuo

합계: 모든 제공업체를 통틀어 한 달에 약 8억(800M) 개의 토큰을 사용할 수 있습니다.

코드 변경 없음
기존 OpenAI SDK의 대상을 localhost:3001/v1로 지정하기만 하면 됩니다:

from openai import OpenAI

client = OpenAI (
    base_url = "http://localhost:3001/v1",
    api_key = "freellmapi-your-unified-key",
)

resp = client.chat.completions.create (
    model = "auto", # 라우터가 사용 가능한 최적의 모델을 선택합니다
    messages = [{
        "role": "user",
        "content": "Summarise the fall of Rome in one sentence."
    }],
)

print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))

그게 전부입니다. 모든 응답에는 X-Routed-Via 헤더가 포함되어 있어 어떤 제공업체가 실제로 요청을 처리했는지 알 수 있습니다.

기술적 하이라이트

자동 장애 조치 (Automatic failover) — 429 (Too Many Requests) / 타임아웃(timeout) / 5xx 에러 발생 시, 라우터는 해당 키의 사용을 잠시 중단하고 체인 내의 다음 제공업체로 최대 20회까지 재시도합니다.

스티키 세션 (Sticky sessions) — 멀티 턴 대화(Multi-turn conversations)는 30분 동안 동일한 모델을 유지합니다. 이는 생각보다 중요한데, 대화 중간에 모델이 바뀌면 미묘한 환각(hallucination) 현상이 급증할 수 있기 때문입니다.

키별 속도 추적 (Per-key rate tracking) — (플랫폼, 모델, 키)별로 RPM, RPD, TPM, TPD 카운터를 관리합니다. 라우터는 항상 제한 범위 내에 있는 키를 선택합니다. 암호화된 키 저장 (Encrypted key storage) — SQLite에 저장되기 전 AES-256-GCM 방식으로 암호화됩니다. 업스트림 제공자(Upstream provider)의 키는 사용자의 기기를 절대 벗어나지 않습니다. 관리자 대시보드 (Admin dashboard) — 키 관리, 폴백 체인(fallback chain) 순서 변경, 분석 데이터 검토, 플레이그라운드(playground)에서의 프롬프트 테스트를 위한 React + Vite UI를 제공합니다. 경량화 (Lightweight) — 유휴 상태에서 약 40MB RAM을 사용하여 Raspberry Pi 4에서도 실행됩니다.

3줄 설치 (Setup in 3 Lines)
git clone https://github.com/tashfeenahmed/freellmapi
cd freellmapi && npm install
cp .env.example .env && npm run dev
localhost:5173을 열고, 제공자 API 키를 추가한 뒤, 통합된 키를 가져오면 끝입니다.

솔직한 부분 (The Honest Part)
README에 명확히 명시되어 있으며, 미리 알고 있어야 할 몇 가지 사항입니다:

• 지능(Intelligence)은 하루 동안 저하됩니다. Gemini 2.5 Pro와 GPT-4o (GitHub Models를 통해 제공)는 일일 제한(daily caps)이 가장 낮습니다. 이 모델들을 모두 사용하면 라우터는 더 작은 모델로 폴백(fallback)합니다. 늦은 시간에는 실질적인 품질이 떨어질 수 있음을 예상해야 하며, 이는 UTC 자정에 초기화됩니다.
• 도구 호출(Tool calling) 및 비전(vision)은 아직 지원되지 않습니다. 현재는 텍스트 전용입니다.
• PR(Pull Requests)은 언제나 환영합니다.
• 지연 시간(Latency)은 예측할 수 없습니다. Cerebras와 Groq는 매우 빠르지만, 다른 곳은 그렇지 않습니다. 사용 가능한 모델 중 하나를 받게 됩니다.
• 개인용으로만 사용하세요. 멀티 테넌트 인증(multi-tenant auth)은 지원하지 않습니다. 이 서비스를 인터넷에 노출하지 마세요.
• 무료 티어(Free tiers)는 예고 없이 변경됩니다. 제공자가 제한을 강화하면 카탈로그가 업데이트될 때까지 429 오류(Too Many Requests)를 보게 될 것입니다.

대상 사용자 (Who This Is For)
✅ 비용을 미리 지불하지 않고 AI 에이전트나 코딩 어시스턴트를 구축하며 프로토타입을 만들고 싶은 분
✅ 한 제공자의 속도 제한(rate limits)에 걸려 원활한 폴백(fallback)을 원하는 연구자 및 학생
✅ 여러 개의 SDK 통합을 유지 관리하는 데 지친 모든 분
❌ 프로덕션 워크로드(Production workloads) — SLA가 보장되는 유료 API를 사용하세요.

간략한 서비스 약관(ToS) 참고
이 프로젝트에는 각 제공자의 약관에 대한 상세한 검토가 포함되어 있습니다. 대부분은 단일 사용자 개인용으로 문제가 없습니다. 주목할 만한 예외 사항은 다음과 같습니다: Cohere의 체험판 약관은 개인/가정용 사용을 명시적으로 금지하며, NVIDIA NIM의 무료 티어는 평가(evaluation) 목적으로만 제한됩니다.

키를 추가하기 전에 README에서 전체 표를 읽어보시기 바랍니다. FreeLLMAPI는 MIT 라이선스를 따르며, 기여자들을 적극적으로 환영하고 있습니다 — 특히 임베딩 (embeddings), 도구 호출 (tool calling), 그리고 새로운 제공업체 (providers)를 추가하는 작업에 대해 환영합니다. → github.com/tashfeenahmed/freellmapi