Sub2API

What is Sub2API?

Sub2API is an open-source AI API gateway platform that helps distribute and manage API quotas from AI product subscriptions. Instead of each user integrating directly with upstream AI services, Sub2API provides platform-generated API keys while it handles authentication, billing-related accounting, load balancing, and request forwarding.

The project is designed for setups where multiple upstream accounts need to be pooled and served through one consistent gateway, including features such as multi-account support, quota-aware scheduling, and controls for concurrency and rate limiting.

Key Features

• Multi-account management for upstream connections (supports multiple upstream account types such as OAuth and API Key), enabling one gateway to serve several upstream accounts.
• API key distribution (generate and manage API keys for users), so users authenticate against Sub2API rather than managing multiple upstream credentials.
• Token-level usage tracking and cost calculation, used to track and compute usage at the token level for billing-related accounting.
• Smart scheduling with sticky sessions, which selects upstream accounts intelligently while keeping session routing stable in multi-account environments.
• Concurrency control and configurable rate limiting (per-user and per-account concurrency limits; request and token rate limits), to prevent overload and manage throughput.
• Admin dashboard for monitoring and management via a web interface.
• External system integration for extending the admin dashboard using iframes (e.g., embedding payment or ticketing systems).

How to Use Sub2API

1. Decide whether you want to self-host or use the official relay service. The repository notes an official relay, PinCC, for users who do not want to self-host.
2. If self-hosting, install Sub2API on a Linux server (amd64 or arm64) with PostgreSQL 15+ and Redis 7+ available.
3. Install using the provided one-click script from the repository, then start the service and enable it at boot.
4. Open the setup wizard in your browser (the README references http://YOUR_SERVER_IP:8080) to configure database/Redis settings and create an admin account.
5. From the admin dashboard, manage settings and user API keys; users then call upstream AI services through the platform using their Sub2API-issued API keys.

Use Cases

• Pooling multiple upstream subscription accounts: use Sub2API to centralize quota usage and serve users through a single gateway while distributing requests across upstream accounts.
• Quota distribution for teams: give team members individual Sub2API API keys while Sub2API tracks token-level usage and manages scheduling and limits.
• Managing throughput with limits: configure per-user and per-account concurrency limits plus request/token rate limits to shape load and reduce the chance of upstream saturation.
• Operational visibility and administration: use the built-in admin dashboard to monitor and manage the gateway instead of relying solely on upstream provider dashboards.
• Extending internal workflows: embed external systems (such as payment or ticketing) into the admin dashboard using iframes to support operational processes.

FAQ

• Is Sub2API tied to a specific domain? The repository states that Sub2API officially uses only sub2api.org and pincc.ai. Other sites using the Sub2API name may be third-party deployments and are not affiliated; users should verify independently.

• How do I deploy Sub2API? The project documents two deployment methods: installing via a script that downloads pre-built binaries from GitHub Releases, or deploying with Docker Compose (including PostgreSQL and Redis containers).

• What upstream accounts does Sub2API support? It supports multiple upstream account types, including OAuth and API Key (as stated in the features list).

• What should I do when using Nginx as a reverse proxy? The README notes that if you use Nginx with Sub2API (or CRS) and Codex CLI, you should add underscores_in_headers on; inside the http block, because Nginx drops headers containing underscores by default and that can break sticky-session routing in multi-account setups.

Alternatives

• Use the official relay service (PinCC): if you don’t want to self-host Sub2API, the repository points to PinCC as the official relay built on Sub2API, intended for users who want ready access without deployment/maintenance.
• Use a self-managed API gateway for quota and routing: if you already run infrastructure, you can look for gateway/route-management solutions that support API keys, authentication, rate limiting, and request forwarding; unlike Sub2API, they may not include token-level usage tracking and AI-subscription-oriented quota distribution.
• Build a custom proxy service: you can implement an application-layer proxy that routes requests to upstream AI providers and enforces limits; compared to Sub2API, this typically requires more engineering work for features like sticky sessions and token-level accounting.
• Use a multi-tenant API management approach: general-purpose API management platforms can centralize auth and throttling, but may require additional customization to match Sub2API’s quota distribution and token-based usage accounting workflow.