Sub2API
AI API Gateway Platform for Subscription Quota Distribution
English | 中文 | 日本語
⚠️ Important Notice
Please read the following carefully before using this project:
- 🚨 Terms of Service Risk: Using this project may violate the terms of service of Anthropic and other upstream providers. Please review the relevant providers' user agreements before use; all risks arising from such use are borne solely by the user.
- ⚖️ Compliant Use: Use this project only in compliance with the laws and regulations of your country or region. Any unlawful use is strictly prohibited.
- 📖 Disclaimer: This project is provided for technical learning and research purposes only. The authors assume no liability for account bans, service interruptions, data loss, or any other direct or indirect damages resulting from the use of this project.
- 🚫 No Commercial Authorization: The developers of this project have never authorized any individual or organization to conduct any form of commercial operation based on this project. Any commercial activity conducted in the name of or based on this project is unrelated to this project and its developers, and all resulting disputes, losses, and legal liabilities shall be borne solely by the party conducting such activity.
❤️ Sponsors
Want to appear here?
WandAPI — an enterprise-grade, stable AI model API gateway built by a core contributor to this project. One API key gives you access to Claude, GPT, Gemini and other leading models, natively compatible with the OpenAI and Anthropic protocols, so Claude Code, Codex and your existing SDKs work by simply changing the Base URL. Real-time routing by latency and upstream health with millisecond-level automatic failover keeps requests online, backed by 99.99% service availability. Pay as you go, with per-request token and cost breakdowns.
Free trial credits: sign up via this exclusive link to claim free trial credits.
Overview
Sub2API is an AI API gateway platform designed to distribute and manage API quotas from AI product subscriptions. Users can access upstream AI services through platform-generated API Keys, while the platform handles authentication, billing, load balancing, and request forwarding.
Features
- Multi-Account Management - Support multiple upstream account types (OAuth, API Key)
- API Key Distribution - Generate and manage API Keys for users
- Precise Billing - Token-level usage tracking and cost calculation
- Smart Scheduling - Intelligent account selection with sticky sessions
- Concurrency Control - Per-user and per-account concurrency limits
- Rate Limiting - Configurable request and token rate limits
- Built-in Payment System - Supports EasyPay, Alipay, WeChat Pay, and Stripe for user self-service top-up, no separate payment service needed (Configuration Guide)
- Admin Dashboard - Web interface for monitoring and management
- Composite Groups - Admin routing layer that resolves requested models to concrete providers for multi-provider groups (Operator Guide)
- External System Integration - Embed external systems (e.g. ticketing) via iframe to extend the admin dashboard
Ecosystem
Community projects that extend or integrate with Sub2API:
| Project | Description | Features |
|---|
Sub2ApiPay | Self-service payment system | Now Built-in — Payment is now integrated into Sub2API, no separate deployment needed. See Payment Configuration Guide |
| sub2api-mobile | Mobile admin console | Cross-platform app (iOS/Android/Web) for user management, account management, monitoring dashboard, and multi-backend switching; built with Expo + React Native |
Tech Stack
| Component | Technology |
|---|
| Backend | Go 1.27.0, Gin, Ent |
| Frontend | Vue 3.4+, Vite 5+, TailwindCSS |
| Database | PostgreSQL 15+ |
| Cache/Queue | Redis 7+ |
Nginx Reverse Proxy Note
When using Nginx as a reverse proxy for Sub2API (or CRS) with Codex CLI, add the following to the http block in your Nginx configuration:
underscores_in_headers on;
Nginx drops headers containing underscores by default (e.g. session_id), which breaks sticky session routing in multi-account setups.
Deployment
Method 1: Script Installation (Recommended)
One-click installation script that downloads pre-built binaries from GitHub Releases.
Prerequisites
- Linux server (amd64 or arm64)
- PostgreSQL 15+ (installed and running)
- Redis 7+ (installed and running)
- Root privileges
Installation Steps
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash
The script will:
- Detect your system architecture
- Download the latest release
- Install binary to
/opt/sub2api
- Create systemd service
- Configure system user and permissions
Post-Installation
# 1. Start the service
sudo systemctl start sub2api
# 2. Enable auto-start on boot
sudo systemctl enable sub2api
# 3. Open Setup Wizard in browser
# http://YOUR_SERVER_IP:8080
The Setup Wizard will guide you through:
- Database configuration
- Redis configuration
- Admin account creation
This is the beginning of the README. Read the rest at the original. Read the full README ↗
