OpenAI-Gemini API 키 로테이터: 다중 LLM 공급자를 위한 Node.js 프록시 서버

섹션별 상세

다수의 API 키를 등록하고 특정 HTTP 상태 코드 발생 시 자동으로 다음 키를 사용하는 로테이션 기능을 제공한다. 기본적으로 429 에러 발생 시 작동하며, 최근 실패한 키를 피하는 지능형 셔플링을 통해 요청 성공률을 극대화한다. 이를 통해 단일 키의 할당량 제한을 넘어 안정적인 서비스 운영이 가능하다.

근거

HTTP 429 상태 코드 발생 시 자동으로 키를 로테이트한다. — Features 섹션의 Automatic Key Rotation 항목

OpenAI와 Gemini의 API 규격을 모두 수용하며 스트리밍 응답을 지원한다. 서버가 응답을 버퍼링하지 않고 클라이언트에게 즉시 전달하므로 실시간 텍스트 생성이 필요한 애플리케이션에 즉시 적용할 수 있다. 헤더를 통해 요청별로 로테이션 기준이 되는 상태 코드를 동적으로 설정할 수도 있다.

근거

SSE/스트리밍 응답에 대해 전체 패스스루를 지원한다. — Features 섹션의 Streaming Support 항목

웹 기반의 현대적인 관리자 패널을 통해 공급자별 키 상태와 사용량을 실시간으로 관리한다. 키를 저장하기 전에 자동으로 유효성을 검사하며, 개별 키나 공급자 전체를 활성화 또는 비활성화할 수 있는 기능을 갖췄다. 다크 모드와 라이트 모드를 모두 지원하여 관리 편의성을 높였다.

bash

curl -X POST "http://localhost:8990/groq/chat/completions" \
 -H "Authorization: Bearer [STATUS_CODES:429][ACCESS_KEY:your-access-key]" \
 -H "Content-Type: application/json" \
 -d '{ "model": "openai/gpt-oss-120b", "messages": [ { "role": "user", "content": "Hello!" } ] }'

Groq 공급자를 통해 OpenAI 호환 API 요청을 보내는 예시

bash

curl -X POST "http://localhost:8990/gemini/models/gemini-2.5-flash:generateContent" \
 -H "x-goog-api-key: [STATUS_CODES:429][ACCESS_KEY:your-access-key]" \
 -H "Content-Type: application/json" \
 -d '{ "contents": [ { "parts": [ { "text": "Hello!" } ] } ] }'

Gemini 호환 API에 대한 로테이션 요청 예시

관리자 패널의 로그인 화면 — Screenshot보안을 위해 설정된 관리자 비밀번호를 입력하는 화면을 보여준다. .env 파일에서 설정한 ADMIN_PASSWORD를 통해 접근이 제어됨을 알 수 있다.

API 키 관리 대시보드 — ScreenshotCerebras, Comet, Gemini, Groq 등 다양한 공급자별로 API 키를 등록하고 관리하는 UI를 보여준다. 각 키의 사용 횟수와 테스트 버튼, 활성화 스위치 등을 통해 직관적인 관리가 가능함을 시각화한다.

실시간 API 요청 로그 화면 — Screenshot최근 100개의 API 요청에 대한 타임스탬프, 엔드포인트, 응답 시간, 사용된 키 정보를 로그 형식으로 보여준다. 어떤 요청이 성공했는지와 특정 요청에 어떤 키가 할당되었는지 실시간으로 모니터링할 수 있다.

내장된 텔레그램 봇을 통해 설정된 모든 모델과 직접 대화할 수 있는 인터페이스를 제공한다. 텍스트 대화뿐만 아니라 이미지 입력(Vision) 및 이미지 생성 모델의 결과물 출력까지 지원한다. 모든 봇 요청은 프록시를 거치므로 자동으로 키 로테이션과 로깅 혜택을 받는다.

용어 해설

API 키 로테이션(API Key Rotation): — 여러 개의 API 키를 번갈아 가며 사용하여 특정 키의 사용량 제한(Rate Limit)을 피하는 기술이다. 하나의 키가 429 에러 등으로 차단될 경우 자동으로 다음 키로 전환하여 서비스 연속성을 보장한다.
서버 전송 이벤트 스트리밍(SSE Streaming): — 서버가 클라이언트에게 실시간으로 데이터를 밀어주는 단방향 통신 방식이다. LLM 응답에서 텍스트가 생성되는 대로 즉시 사용자에게 보여주는 기능을 구현할 때 필수적으로 사용된다.
속도 제한(Rate Limiting): — 단위 시간당 허용되는 API 요청 횟수를 제한하는 정책이다. 주로 HTTP 429(Too Many Requests) 상태 코드로 응답하며, 서비스 과부하 방지와 공정한 자원 배분을 목적으로 한다.

기술

Node.js
JavaScript
Telegram Bot API
OpenAI API
Gemini API

활용 사례

다중 API 키 기반의 안정적인 챗봇 서버
LLM API 사용량 모니터링 및 로깅 시스템
텔레그램 기반의 멀티 모델 채팅 인터페이스

언급된 리소스

GitHubopenai-gemini-api-key-rotator GitHub