sub2api

1. Project Overview

Sub2API is an open-source Go-based API gateway that consolidates Claude, OpenAI, Gemini, Grok, and Antigravity subscriptions into unified, OpenAI/Anthropic-compatible API endpoints, letting teams pool and manage shared subscription quota through a single self-hosted service.

2. Background & Positioning

Individual AI subscriptions (Claude Pro/Max, ChatGPT Plus, Gemini Advanced, and similar plans) are priced for single-user, browser-based usage, yet developers increasingly want programmatic access through native CLI tools and SDKs. Sub2API was built to bridge that gap: it turns one or many subscription accounts into an API-compatible gateway, so a team or community can share quota, track usage per token, and route requests intelligently across accounts and providers.

Compared to general-purpose LLM proxy or router projects that mainly forward API-key traffic, Sub2API focuses specifically on subscription-based accounts (OAuth-authenticated consumer plans), adding account pooling, sticky-session scheduling, and built-in billing/payment rails so that shared access can be operated as a small hosted service rather than a personal script.

3. Feature Categories

🔑 Account & Access Management — 4 core capabilities, e.g. OAuth account binding, API Key account binding, dynamic API key issuance, per-key lifecycle control. Purpose: onboard and manage many upstream subscription accounts and downstream user keys from one dashboard.

⚖️ Scheduling & Traffic Control — 4 core capabilities, e.g. intelligent account selection, sticky sessions, per-user concurrency limits, per-account concurrency limits, configurable request/token rate limits. Purpose: distribute load evenly across pooled accounts while protecting each account from being throttled or flagged upstream.

💳 Billing & Monetization — 4 core capabilities, e.g. token-level usage metering, built-in payment integrations (EasyPay, Alipay, WeChat Pay, Stripe), self-service top-up, billing circuit breaker. Purpose: let operators run cost-sharing or paid-access groups with accurate, auditable usage accounting.

🧩 Multi-Provider Routing — 5 supported providers: Claude (Anthropic), OpenAI (including Codex), Gemini (Google), Grok/xAI, and Antigravity (hybrid scheduling). Purpose: expose heterogeneous upstream providers behind consistent, familiar API shapes.

🖥️ Admin Dashboard & Ops — 4 core capabilities, e.g. Vue 3 web console, real-time monitoring, WebSocket ingress management for Codex CLI, asynchronous image-task polling. Purpose: give operators visibility and control without needing to touch the command line day-to-day.

4. Key Highlights

• Subscription pooling ("carpooling") — combine multiple Claude/OpenAI/Gemini/Grok accounts into one gateway so quota costs can be shared across a team or user base.
• Native tool compatibility — designed so existing CLI tools and SDKs built against Anthropic/OpenAI-style APIs work with minimal or no changes.
• Token-precise billing — every request is metered at the token level, enabling fair cost allocation and pay-as-you-go top-ups.
• Sticky-session smart scheduling — keeps a conversation pinned to the same upstream account when needed, avoiding context loss across multi-turn tool sessions.
• Composite provider groups — route a single logical model endpoint across multiple providers or accounts for redundancy and load balancing.
• Multiple deployment paths — one-line install script, Docker Compose, Apple Container (macOS/Apple Silicon), or build-from-source, covering both quick trials and production rollouts.

5. Use Cases by Role

• General developers: Access Claude, OpenAI, Gemini, and Grok through one consistent API endpoint and API key, without juggling separate SDKs or credentials for each provider.
• DevOps/SRE: Deploy via Docker Compose with PostgreSQL and Redis, configure rate limits, trusted proxies, and circuit breakers to keep a shared gateway stable under load.
• Community/team operators: Pool subscription costs across a group, issue individual API keys, and use the built-in payment integrations to manage shared or paid access.
• Project managers: Use the admin dashboard to monitor usage, spending, and account health across an organization without needing engineering support for routine oversight.

6. Getting Started

Find what you need — start with the repository README (English and 中文) and the deploy/README.md for deployment-specific guidance:

git clone https://github.com/Wei-Shaw/sub2api.git

Install / integrate — the fastest path is the one-line install script for Linux:

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

or Docker Compose for a fully containerized setup (includes PostgreSQL and Redis):

mkdir -p sub2api-deploy && cd sub2api-deploy
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
docker compose up -d

Contribute — fork the repository, open a pull request against main, and use GitHub Issues to report bugs or propose features:

gh repo fork Wei-Shaw/sub2api --clone

7. Project Structure

sub2api/
├── backend/     # Go service: config, models, request handlers, provider gateway logic
├── frontend/    # Vue 3 + Vite + TailwindCSS admin dashboard
├── deploy/      # Docker Compose files, env templates, install/upgrade scripts
└── openspec/    # OpenAPI specifications for the exposed gateway endpoints

• backend/cmd/server — main entrypoint for the Go binary.
• deploy/install.sh / deploy/docker-deploy.sh — one-line installers for script-based and Docker-based deployment.
• frontend/ — the web console used for account, key, billing, and monitoring management.

8. Related Ecosystem

• Upstream dependencies: Go 1.25.7 with the Gin web framework and Ent ORM on the backend; Vue 3.4+, Vite 5+, and TailwindCSS on the frontend; PostgreSQL 15+ for storage and Redis 7+ for caching and queues.
• Upstream subscription providers: Anthropic (Claude), OpenAI (including Codex), Google (Gemini), and xAI (Grok) — Sub2API sits in front of these as a gateway rather than replacing them.
• Companion projects: sub2api-mobile, a cross-platform mobile admin console for managing a deployed instance on the go.

9. License

Sub2API is released under the GNU Lesser General Public License v3.0 (LGPL-3.0).

• ✅ Free to use, study, and modify the source code, including for internal or educational purposes.
• ✅ Free to self-host for personal or team use, including sharing subscription costs within a private group.
• ❌ The project explicitly states it has not authorized any individual or organization to operate it as a commercial service.
• ℹ️ Using Sub2API to access upstream providers may conflict with those providers' own Terms of Service; the maintainers describe the project as intended for technical learning and research purposes, and operators are responsible for their own compliance and account risk.

10. FAQ

Q: What AI providers does Sub2API support?
A: Claude (Anthropic), OpenAI (including Codex), Gemini (Google), Grok/xAI, and Antigravity, unified behind compatible API endpoints. See the README for the current list.

Q: What's the fastest way to try it out?
A: Use the Docker Compose quick-start, which provisions PostgreSQL and Redis alongside the gateway automatically:

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

Q: Is running Sub2API against my subscription accounts against the provider's rules?
A: The maintainers note it may conflict with upstream providers' Terms of Service and disclaim liability for account bans; review the license and disclaimers in the README before deploying.

Q: Can I use Sub2API to run a paid service for others?
A: The project ships built-in payment integrations (EasyPay, Alipay, WeChat Pay, Stripe) for cost-sharing within a group, but the maintainers have not authorized commercial operation of the project itself — check the license terms first.

Q: Where do I report bugs or request features?
A: Through GitHub Issues on the main repository.

11. Quick Links

• Repository: https://github.com/Wei-Shaw/sub2api
• Chinese README: README_CN.md
• Deployment guide: deploy/README.md
• Issues / community discussion: GitHub Issues
• Releases: GitHub Releases

12. Summary

Sub2API turns scattered AI subscription accounts into a single, manageable, API-compatible gateway with token-level billing, smart scheduling, and a full admin dashboard. It is best suited for developers and small teams who want to share subscription costs and access Claude, OpenAI, Gemini, and Grok through one consistent interface, provided they carefully review the upstream Terms of Service and licensing implications before deploying it.