sub2api

Product Introduction

1. Definition: Sub2API is an open-source, self-hosted AI API gateway and relay service. Technically, it is a middleware platform written in Go (Golang) that sits between end-users and multiple upstream AI service providers like Anthropic (Claude), OpenAI, Google (Gemini), and xAI (Grok).
2. Core Value Proposition: It exists to consolidate and distribute access to expensive, subscription-based AI model APIs. Its primary value is enabling cost-sharing for AI API access by pooling subscription quotas and providing a unified, programmable interface, thereby solving the problem of managing multiple AI subscriptions individually.

Main Features

1. Multi-Account & Multi-Provider Management: The platform supports adding numerous upstream accounts from different providers using OAuth or API Key authentication. It abstracts the complexity of managing these distinct accounts, treating them as a unified pool of resources. Administrators can configure models, rates, and priorities for each account.
2. Precise Token-Level Billing & Rate Limiting: Sub2API implements granular usage tracking at the token level for both input and output, enabling accurate cost calculation per end-user request. It enforces configurable rate limits based on requests per minute and tokens per minute for each user API key, preventing abuse and ensuring fair quota distribution.
3. Intelligent Load Balancing with Sticky Sessions: Beyond simple round-robin, the gateway features smart scheduling algorithms. A key technical component is "sticky session" routing, which uses a session_id header to pin a user's conversation to a specific upstream account for a duration. This is critical for maintaining conversational context in AI chat applications and is implemented via the backend's routing logic, requiring proper Nginx configuration (underscores_in_headers on;) to function.
4. Built-In Payment & Monetization System: A significant operational feature is the integrated payment gateway supporting EasyPay, Alipay, WeChat Pay, and Stripe. This allows platform operators to offer self-service top-up for end-users without developing a separate billing infrastructure, turning Sub2API into a full-stack AI API reselling platform.
5. Composite Groups (Admin Routing Layer): This advanced feature allows administrators to create logical model groups (e.g., "gpt-4") that can be resolved to multiple concrete providers. When a user requests gpt-4, the system can intelligently route the call to available accounts from OpenAI, Azure, or other compatible endpoints, providing redundancy and failover.

Problems Solved

1. Pain Point: The high individual cost and administrative overhead of maintaining separate paid subscriptions (Claude Pro, ChatGPT Plus, etc.) for development and testing. It directly addresses AI API cost optimization and subscription management fatigue.
2. Target Audience: Cost-conscious development teams, indie developers, startups, AI tooling companies, and researchers who require reliable, multi-model API access without the prohibitive expense of official enterprise plans. It also serves SaaS entrepreneurs looking to resell AI API capacity.
3. Use Cases: Unified AI Backend for Applications: Building a single application that can leverage Claude, GPT, and Gemini models through one API endpoint. Development & Testing: Providing team members with shared, metered API access for prototyping. Commercial AI API Relay Service: Operating a service like the listed sponsors (CCTK.AI, OpenModel, etc.) using this very stack.

Unique Advantages

1. Differentiation: Unlike using a single provider's API or manually switching keys, Sub2API provides abstraction, pooling, and fine-grained control. Compared to other open-source gateways, its built-in payment system and focus on subscription quota distribution for consumer AI products (vs. cloud credits) is a key differentiator. It's designed for the ecosystem of Claude Code, Codex, and other coding tools.
2. Key Innovation: The combination of token-level accounting with a user-facing self-service payment portal in a single open-source package. This creates a complete economic and technical loop for redistributing AI API capacity. The composite group feature is also an innovative approach to creating provider-agnostic model endpoints.

Frequently Asked Questions (FAQ)

1. Is using Sub2API against the terms of service of AI providers like Anthropic? Yes, the project maintainers explicitly warn that using Sub2API to pool or resell access from individual consumer subscriptions (like Claude Pro) likely violates the provider's Terms of Service, risking account bans. Users assume all associated risks.
2. What is the primary tech stack for deploying Sub2API? The backend is built with Go 1.26.5 and the Gin web framework, the frontend uses Vue 3.4+ with Vite and TailwindCSS, and it requires PostgreSQL 15+ and Redis 7+ for data persistence and caching. It is typically deployed behind an Nginx reverse proxy.
3. How does Sub2API handle concurrency and prevent abuse? It implements dual-layer concurrency control, limiting simultaneous requests per user API key and per upstream provider account. Combined with configurable request-per-minute and token-per-minute rate limits, this prevents any single user from exhausting shared resources.
4. Can I use Sub2API to support AI coding tools like Claude Code or Cursor? Yes, this is a primary use case. Sub2API acts as a compatible backend for these tools. You would configure the AI tool to use your Sub2API endpoint and generated key instead of a direct provider key, granting access to the models you've configured on the platform.
5. What is the "sticky session" feature and why is it important? Sticky session routing uses a session_id header to ensure a user's sequential chat requests are sent to the same upstream AI account. This is crucial for maintaining conversation memory and context in chat applications, as switching accounts mid-conversation would lose the context. Proper Nginx configuration is required to pass the underscore header.