Sub2API – Open-Source AI API Gateway & Multi-Account Management

1. What Is Sub2API

Sub2API is an open-source AI API gateway platform for distributing and managing API quotas from AI product subscriptions, developed primarily by Wesley Liddick. Through API keys issued by the platform, users can unify upstream subscriptions to Claude, OpenAI, Gemini, and Antigravity behind a single gateway that handles authentication, billing, load balancing, and request forwarding. Its core value is a "shared subscription" model that splits costly plan costs fairly, backed by a built-in payment system, intelligent scheduling, and token-level precise billing. The project is open on GitHub with 30.9k stars, making it a popular choice for individuals and teams building private AI API distribution systems.

Technical positioning and domain: AI service management and distribution — solving multi-account chaos, opaque cost sharing, and fragmented API key governance. In the AI gateway space it positions around "subscription quota distribution" rather than generic multi-model proxying.

Development background: Led by developer Wesley Liddick and hosted at github.com/Wei-Shaw/sub2api, the project has grown into an active open-source effort with 30.9k stars, 6.3k forks, and 1.5k+ issues, and has appeared on the Trendshift trending list. It is licensed under GNU LGPL v3.0 (or later), with an explicit statement prohibiting unauthorized commercial operations and reminding users that Terms-of-Service risks are their own responsibility.

Core value: Through multi-account management, intelligent scheduling, and token-level billing, Sub2API helps users reduce AI subscription costs within the rights their accounts already grant, while providing a unified API entry point, built-in payment, and a web admin console — packaging "multi-account ops + billing + distribution + monitoring" into a one-stop private gateway.

Technical characteristics: The backend uses Go 1.25.7 + Gin + Ent, the frontend uses Vue 3.4+ + Vite 5+ + TailwindCSS, backed by PostgreSQL 15+ and Redis 7+. It supports OAuth and API Key authentication, sticky sessions, user-level and account-level concurrency and rate limits, and ships with HTTP/2 (h2c) support plus an HTTP/1.1 fallback for reverse-proxy performance and legacy client compatibility.

2. Key Features

• Multi-account management: Supports OAuth and API Key authentication to unify upstream accounts for Claude, OpenAI, Gemini, and Antigravity, with centralized visibility into account health, quota, and authorization status — keeping upstream credentials out of individual team members' hands.

• API key distribution: Issues scoped downstream API keys with customizable prefixes (e.g. sk-) so admins can grant, revoke, and rotate keys for members or customers without touching upstream accounts.

• Token-accurate billing: Tracks usage and cost per request by parsing provider usage fields (prompt/completion tokens), mapping to configured upstream cost tables, and aggregating by downstream key/user — making shared-subscription cost splits transparent and auditable.

• Intelligent scheduling: Picks healthy upstream accounts and supports sticky sessions that pin a conversation ID to one upstream, preserving context continuity for multi-step agent workflows, file uploads, and long threads.

• Concurrency control: Two-tier user-level and account-level limits via independent semaphores across global, upstream, and downstream-key dimensions — requests queue or fail fast based on policy to protect upstream session caps.

• Rate limiting: Configurable request QPS and token velocity to dodge upstream provider risk controls, plus server-side fallback rate limiting on /auth/register, /auth/login, /auth/login/2fa, and /auth/send-verify-code with fail-close behavior when Redis is down.

• Built-in payment system: Supports EasyPay, official Alipay, official WeChat Pay, and Stripe for self-service top-ups — no need to deploy a standalone payment service. Configuration details are in the official docs/PAYMENT_CN.md guide.

• Admin console: A Vue 3 web UI for live monitoring, statistics, account and key management, quota and billing rules, plus an in-dashboard "check for updates" button with auto-detect, one-click apply, and rollback support.

• External system integration: Supports embedding external systems (ticketing, billing, support) via iframe to build a unified ops console, and pairs with community projects like sub2api-mobile for user/account management and dashboards on mobile.

3. How to Use

1. Requirements: Script install needs a Linux server (amd64 or arm64) with PostgreSQL 15+ and Redis 7+ preinstalled and root privileges. Docker Compose deployment needs Docker 20.10+ and Docker Compose v2+. Source builds additionally require Go 1.21+, Node.js 18+, and pnpm (backend recommends Go 1.25.7).

2. Install: Recommended one-line script: curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash — auto-detects architecture, downloads the binary to /opt/sub2api, and creates the systemd service. Or use the Docker Compose one-line docker-deploy.sh which auto-generates secure credentials and a .env file.

3. Initialize: Open http://<server-ip>:8080 for the setup wizard to configure the database, Redis, and admin account; the wizard writes out the generated config.yaml. If you pre-create config.yaml, you must temporarily move it aside to trigger the wizard (admin accounts can only be created via the wizard; default.admin_email won't auto-provision).

4. Authorize upstream accounts: In the admin console, add Claude, OpenAI, Gemini, and Antigravity accounts and complete OAuth or API Key authorization. Antigravity accounts expose dedicated endpoints /antigravity/v1/messages (Claude) and /antigravity/v1beta/ (Gemini), and can enable a hybrid scheduling mode that routes general endpoints to the same account.

5. Issue keys and billing: Generate independent API keys for downstream users with per-key quotas, billing rules, concurrency, and rate limits. With built-in payment configured (EasyPay/Alipay/WeChat/Stripe), users can self-service top up; all billing is aggregated from token-level real-time cost data.

6. Security and reverse proxy: For production, terminate TLS at a reverse proxy, put WAF/CDN as the first defense layer, and add underscores_in_headers on; to Nginx (it drops session_id headers by default, breaking sticky sessions). Set security.url_allowlist.allow_insecure_http: false to restrict outbound to HTTPS only and avoid plaintext API key transmission.

4. Pros and Cons

5. Comparison with Similar Tools

Selection guidance: For individuals and small teams that want to share Claude Pro / ChatGPT Plus subscriptions via a fair token-level billing model with built-in payment, Sub2API is the best-matched open-source option today — its sticky sessions and subscription-quota distribution are especially valuable for agent tool-calling workloads. If you only need unified multi-model proxying and don't care about subscription sharing or billing, One API is simpler with richer community plugins. For low-cost relay with pay-as-you-go billing, New API and its forks are stronger thanks to channel aggregation and Midjourney support. Enterprise shops needing strict IAM and compliance audit should layer WAF/CDN and trusted-proxy config on Sub2API, or evaluate commercial AI Gateway options.

6. Editor's Take

Sub2API's "subscription quota distribution" positioning sets it apart in the AI gateway space. Its value isn't about adding more model adapters — it's about packaging "multi-account ops + billing + distribution + payment + monitoring" into a one-stop private gateway, turning a gray-zone operation like "five friends sharing a Claude Max account" into an auditable, billable, operable engineering solution. The Go 1.25.7 + Gin + Ent backend ensures high concurrency and type safety, Vue 3.4+ + TailwindCSS gives a modern admin experience, and details like HTTP/2 (h2c) and sticky sessions reflect genuine production-link thinking.

That said, compliance risk and upstream ToS conflicts are unavoidable — the README's "Important Notice" section explicitly puts account-ban and service-outage liability on the user. Before pooling paid seats, obtain legal/compliance sign-off. Overall, Sub2API is a highly innovative tool in both engineering and product positioning, and its 30.9k stars and Trendshift listing confirm strong market demand for private AI gateways.

7. Use Cases

• Subscription pooling: Split Claude Pro / ChatGPT Plus costs across members with token-level billing for fair cost sharing, and let members self-service top up via built-in payment — lowering the barrier to premium AI models.

• Team AI resource governance: Centralize multiple AI service accounts, issue revocable scoped keys to engineers, protect upstream quotas with two-tier concurrency limits and sticky sessions, and gain centralized monitoring and quota auditing.

• Personal aggregation: Combine Claude, OpenAI, Gemini, and Antigravity accounts into a single entry point, using groups to prevent Anthropic Claude and Antigravity Claude from mixing within the same context.

• Reseller / hobby gateway: Stand up a private relay with built-in EasyPay/Alipay/WeChat/Stripe so downstream users get stable AI access plus self-service top-up, with custom billing policies and quota management.

• Dev/staging parity: Point local OpenAI-compatible SDKs at Sub2API so engineers test against the same routed upstream pool used in shared prod keys — reducing "works on my key" drift across environments.

8. FAQ

Q: Is Sub2API free and open source? What license does it use?
A: The project is open at github.com/Wei-Shaw/sub2api under the GNU Lesser General Public License v3.0 (LGPL-3.0) or later, so the code is free to study. However, the README explicitly states that no individual or organization has been authorized to run commercial operations based on this project, and any commercial activity carried out in the project's name is unrelated to the developers. Before use, read the four important notices — ToS risk, compliant use, disclaimer, and no commercial authorization — account-ban and similar risks are the user's responsibility.

Q: Which upstream AI services does Sub2API support?
A: Currently Claude, OpenAI, Gemini, and Antigravity via OAuth and API Key. Antigravity accounts expose dedicated endpoints /antigravity/v1/messages for Claude models and /antigravity/v1beta/ for Gemini models, with an optional hybrid scheduling mode that routes general endpoints to the same account. New upstream adapters land via PRs — check the latest Release Notes on GitHub before planning exotic endpoints.

Q: How does token-level billing work?
A: The gateway parses each request's provider usage fields (prompt/completion tokens), maps them to upstream cost tables configured in the admin console, and aggregates by downstream API key/user. With EasyPay/Alipay/WeChat/Stripe built-in, users can self-service top up; billing.circuit_breaker fail-closes on billing errors to avoid incorrect charges.

Q: Which deployment options does Sub2API support, and which is recommended?
A: Three options. Option 1 — script install (recommended): curl -sSL .../install.sh | sudo bash downloads the prebuilt binary, configures systemd, and supports in-dashboard online updates with rollback. Option 2 — Docker Compose (recommended): docker-deploy.sh auto-generates JWT_SECRET, TOTP_ENCRYPTION_KEY, and POSTGRES_PASSWORD; the docker-compose.local.yml local-directory variant is recommended for easier backup and migration. Option 3 — source build: for development/customization; note that the -tags embed flag embeds the frontend into the binary — without it, the built program has no web UI.

Q: How do I create the admin account? Why does first login show "invalid email or password"?
A: The initial admin account can only be created via the setup wizard on first boot (visit http://<host>:8080); default.admin_email / default.admin_password in config.yaml are not used to create an admin and are only retained for historical reasons. If you pre-create config.yaml, the wizard is skipped and the users table is empty, so login fails. Recommended: skip the cp config.example.yaml config.yaml step and let the wizard generate the config. If you already created one, temporarily move it aside to trigger the wizard, then restore it and restart.

Q: How are concurrency control and rate limiting implemented?
A: Two-tier user-level and account-level concurrency limits via independent semaphores across global, upstream-account, and downstream-key dimensions; requests queue or fail fast per your policy. Rate limiting covers configurable QPS and token velocity, plus server-side fallback rate limiting on /auth/register, /auth/login, /auth/login/2fa, and /auth/send-verify-code with fail-close behavior when Redis is down. Combined with gateway.upstream_response_read_max_bytes and similar caps, this prevents memory amplification from anomalous upstream responses.

Q: What if sticky sessions break behind an Nginx reverse proxy?
A: Add underscores_in_headers on; to the http block of your Nginx config. Nginx drops headers with underscores (such as session_id) by default, which breaks sticky sessions in multi-account setups. Also terminate TLS at the reverse proxy, put WAF/CDN as the first defense layer, and set security.url_allowlist.allow_insecure_http: false to restrict outbound to HTTPS and avoid plaintext API key transmission.

9. Project Links

• GitHub repository: https://github.com/Wei-Shaw/sub2api
• Payment configuration guide: https://github.com/Wei-Shaw/sub2api/blob/main/docs/PAYMENT_CN.md
• Chinese README: https://github.com/Wei-Shaw/sub2api/blob/main/README_CN.md