TL;DR

Sub2API는 Claude, OpenAI, Gemini, Antigravity, Grok 등 여러 구독형 AI 공급자를 단일 엔드포인트로 통합해 API 키 발급, 토큰 단위 과금, 계정 풀링, 스티키 세션과 스마트 스케줄링을 제공하는 오픈소스 게이트웨이다. 플랫폼은 Go 백엔드와 Vue 프론트엔드로 구성되며 Docker Compose·원클릭 스크립트·소스 빌드 등 다양한 배포 경로를 제공하므로 빠른 PoC와 운영 전환이 모두 가능하다. 다만 README에서 일부 공급자의 이용약관을 위반할 수 있다는 점과 Sora 기능의 임시 중단, HTTP 허용 설정이 보안상 위험을 초래할 수 있음을 명확히 경고하고 있어 도입 전 법적·보안적 검토가 필요하다.

주요 기능

• 여러 상위 계정을 하나의 플랫폼에서 관리하고 사용자에게 플랫폼 발급 API Key를 제공한다. 이 기능은 OAuth와 API Key 기반 계정 유형을 모두 지원해 관리자가 다양한 공급자 계정을 통합할 수 있도록 한다. 관리자는 대시보드를 통해 계정 상태와 사용량을 관찰하고 필요 시 계정 재인가나 갱신 작업을 수행할 수 있다.
• 토큰 단위 사용량 집계와 정확한 과금 계산을 통해 비용 분담을 구현한다. Sub2API는 upstream 응답의 rate-limit·quota 관련 헤더를 기록하고 내부적으로 토큰 소비를 집계하여 사용자별 청구에 반영한다. 이 방식은 계정 공유 환경에서 발생하는 비용 분배의 투명성을 확보한다.
• 스마트 스케줄링과 스티키 세션을 통해 요청을 적절한 상위 계정으로 라우팅하고 세션 일관성을 유지한다. 스케줄러는 계정 상태(예: 401/403/429 응답)를 관측해 계정을 일시 제외하거나 재시도 정책을 적용하며, 스티키 세션은 스트리밍·대화형 흐름에서 연결된 계정을 유지한다. 동시성·레이트 리밋 제어 기능으로 과도한 병렬 요청이 특정 계정에 집중되는 것을 방지한다.
• 내장 결제 및 관리 대시보드를 제공해 별도의 결제 시스템 불필요 배포를 지원한다. EasyPay, Alipay, WeChat Pay, Stripe 같은 결제 옵션을 바로 연결할 수 있으며 관리 콘솔에서 업데이트 및 롤백을 수행할 수 있다. 이로써 SaaS형 배포나 팀용 내부 플랫폼을 빠르게 운영 환경에 올릴 수 있다.

어떻게 동작하는가

Sub2API는 Go 기반 백엔드가 인증·요금집계·스케줄링·프록시 전달을 담당하고 Vue 프론트엔드가 관리 대시보드를 제공하는 전형적인 API 게이트웨이 아키텍처를 채택한다. 플랫폼은 upstream 계정 풀을 유지하며 요청별로 적합한 계정을 선택해 요청을 포워딩하고 응답 헤더에서 쿼터·레이트 정보를 추출해 내부 카운터에 반영한다. 스티키 세션과 동시성 제한, 하이브리드 스케줄링 같은 정책이 라우팅 결정과 계정 제외 로직을 보완하며 필요시 관리자 UI에서 설정을 변경할 수 있다.

해결 문제

여러 구독형 AI 서비스 계정을 개별 애플리케이션이나 사용자에게 직접 배포하는 복잡성을 제거하고 중앙에서 키 발급·쿼터 분배·비용 정산을 가능하게 한다. 플랫폼은 토큰 단위 집계와 정밀한 스케줄링으로 계정 공유 시 발생하는 사용량 불균형과 과금 불투명성을 완화한다. 또한 내장 결제와 관리자 대시보드를 제공해 SaaS 또는 내부 개발 팀의 빠른 운영 착수와 관리 편의성을 높인다.

지금 주목받는 이유

이 프로젝트는 GitHub에서 많은 별(star 29814)을 보유하며 다양한 서드파티 스폰서와 통합 생태계를 README에 명시하고 있다. 여러 주요 상위 제공자(Claude, OpenAI, Gemini, Antigravity, Grok 등)를 하나의 엔드포인트로 통합하려는 명확한 실용적 니즈와 즉시 배포 가능한 스크립트·도커 템플릿이 결합되어 높은 관심을 얻었다. 다만 프로젝트 자체가 일부 공급자의 서비스 약관을 위반할 수 있다는 경고를 README에서 명시하고 있어 채택 시 법적·운영 리스크를 반드시 검토해야 한다.

차별점

• 결제 시스템을 기본 내장해 별도 결제 서비스 배포 없이도 사용자가 셀프탑업을 할 수 있게 구성되어 있다. README에 따르면 EasyPay, Alipay, WeChat Pay, Stripe를 바로 연결할 수 있으며 결제 구성 가이드가 제공된다. 이 점은 결제 인프라를 따로 구축해야 하는 경쟁 솔루션 대비 초기 운영 부담을 줄인다.
• 상위 계정 풀링과 스티키 세션 기반 라우팅으로 대화형·스트리밍 워크로드에서 세션 일관성을 유지할 수 있다. Nginx 설정 예시와 스티키 세션 관련 설명은 프록시 환경에서 세션 헤더 유실이 라우팅에 미치는 영향을 구체적으로 다루고 있다. 또한 하이브리드 스케줄링으로 Antigravity 전용 엔드포인트를 분리해 운용할 수 있어 공급자별 정책 차이를 관리할 수 있다.
• 설치 옵션이 스크립트 설치, Docker Compose, 소스 빌드로 다양하게 제공되어 운영 환경 요구사항에 따라 유연하게 배포할 수 있다. 자동 설치 스크립트는 바이너리 설치와 systemd 서비스 등록을 자동으로 수행하며, Docker 흐름은 데이터 디렉터리 기반 로컬 배포를 권장해 마이그레이션과 백업이 쉬운 구성을 제공한다. 이로써 빠른 PoC에서 프로덕션 전환까지 이행 비용을 낮춘다.

사용 사례

• 팀 또는 조직 차원에서 다수 구독을 중앙에서 관리하고 비용을 분담하는 내부 인프라로 활용할 수 있다. 플랫폼은 API Key 발급과 토큰 단위 사용량 집계를 제공하므로 팀별·프로젝트별 과금 정산을 자동화할 수 있다. 또한 스티키 세션과 동시성 제한 정책으로 실사용 환경에서 안정적인 라우팅을 유지할 수 있다.
• SaaS 제공자가 여러 외부 모델 공급자를 통합해 단일 호환 API를 고객에게 제공하는 프록시·리레이 서비스로 사용할 수 있다. Sub2API는 upstream별 엔드포인트 매핑과 하이브리드 스케줄링을 지원하므로 특정 고객 요청을 선호 공급자나 전용 Antigravity 경로로 라우팅할 수 있다. 내장 결제와 관리 대시보드는 멀티테넌트 요금 청구 체계를 간소화한다.
• 개발·테스트 환경에서 간단 모드(RUN_MODE=simple)를 사용해 별도 SaaS 기능 없이 빠르게 모델 접근을 검증하는 용도로 적합하다. 간단 모드는 청구 절차를 숨기고 개발 편의성을 우선하며 로컬 또는 내부망에서 손쉽게 서비스 동작을 확인할 수 있다. 다만 간단 모드는 프로덕션 사용 시 추가 보안·설정 검토가 필요하다.

시작하기

Docker Compose 또는 제공된 one-click 설치 스크립트를 이용하면 가장 빠르게 배포할 수 있다. Docker 방식은 deploy 스크립트를 내려받아 docker-compose.local.yml과 .env 예시를 생성하고 자동으로 비밀키를 생성한 후 docker compose up -d로 서비스를 기동하는 흐름을 따른다. 사전 요구사항으로 Docker 20.10+와 Docker Compose v2+, 또는 스크립트 설치 시 Linux 서버와 PostgreSQL·Redis가 준비되어 있어야 하며 초기 관리자 계정은 설정 마법사에서 생성하도록 설계되어 있다.

요구사항

• 서버 런타임 요구사항으로 PostgreSQL 15 이상과 Redis 7 이상이 필요하며, 설치 스크립트 기반 배포는 루트 권한을 요구한다. Docker Compose 기반 배포는 Docker 20.10 이상 및 Docker Compose v2 이상을 요구하며 로컬 디렉터리 버전은 데이터 마이그레이션과 백업을 단순화한다. 소스 빌드로 개발 환경을 구성하려면 Go 1.21+, Node.js 18+, 그리고 pnpm 등의 빌드 도구가 필요하다.