DEV Community

Cover image for Open Source Project (No.73): Sub2API - All-in-One Claude/OpenAI/Gemini Subscription-to-API Relay
WonderLab
WonderLab

Posted on

Open Source Project (No.73): Sub2API - All-in-One Claude/OpenAI/Gemini Subscription-to-API Relay

#ai #opensource #apigateway #claude

Introduction

"Fluidize your AI subscription quotas and maximize the value of every penny."

This is the No.73 article in the "One Open Source Project per Day" series. Today, we are exploring Sub2API (also known as CRS2).

With the rise of native AI power-tools like Claude Code and GitHub Copilot, many developers find themselves with multiple AI subscriptions (such as Claude Pro or OpenAI Plus). However, these subscriptions often come with usage limits or idle quotas. How can you consolidate these scattered subscription resources and distribute costs efficiently across different tools and users? Sub2API provides a perfect open-source solution.

It is more than just a simple forwarder; it is a full-featured API proxy platform that handles the entire pipeline — from account management and quota distribution to automated billing and built-in payments. It is particularly well-suited for team sharing, "carpooling" (shared-cost usage), or individual multi-account integration.

What You Will Learn

  • The core positioning of Sub2API and the pain points it solves.
  • Supported mainstream models and subscription types.
  • Core features: Multi-account management, intelligent scheduling, and Token-level billing.
  • Rapid deployment methods: Script installation and Docker Compose.
  • How to use Sub2API to build your own AI API relay service.

Prerequisites

  • Basic understanding of AI model APIs (OpenAI, Claude, Gemini, etc.).
  • Fundamental Linux command-line experience.
  • Familiarity with Docker or containerized deployment concepts.

Project Background

Project Overview

Sub2API is an AI API gateway platform developed in Go. Its core logic is to "pool" AI subscriptions from various channels (including OAuth-authenticated accounts, Session Keys, or standard API Keys).

With Sub2API, you can:

  1. Aggregate Resources: Plug in multiple Claude Pro or OpenAI accounts and output a single, unified standard API.
  2. Share Costs: Supports a "carpooling" mechanism with a built-in billing system to charge by usage.
  3. Seamless Integration: The generated APIs work flawlessly with native tools like Claude Code, OpenClaw, and more, without complex client-side configuration.

Author/Team

  • Maintained by: Wei-Shaw
  • Ecosystem: The project enjoys active community support, including a mobile admin console (sub2api-mobile) and other surrounding tools.

Project Data

  • 📄 Core Repository: Wei-Shaw/sub2api
  • 🛠️ Tech Stack: Go (Gin, Ent), Vue 3, PostgreSQL, Redis
  • 📄 License: LGPL-3.0
  • 📈 Stats: Over 22k Stars on GitHub (Note: May include historical repository data or high community interest).

Main Features

Core Utility

Sub2API solves the "resource island" problem in AI usage:

Upstream Account Pool (Claude, OpenAI, Gemini)
      ↓ Integration
Sub2API Platform Layer (Auth, Billing, Load Balancing, Session Persistence)
      ↓ Unified Distribution
Downstream Applications (IDEs, Chat clients, Scripts)
Enter fullscreen mode Exit fullscreen mode

Key Features

  1. Multi-Account Management: Supports various upstream account types and automatically handles session persistence.
  2. Precise Billing: Token-level usage tracking and cost calculation with customizable rates.
  3. Smart Scheduling: Supports Sticky Sessions and load balancing to ensure continuity in long conversations.
  4. Built-in Payment System: Native support for Alipay, WeChat Pay, Stripe, etc., allowing users to top up autonomously.
  5. Concurrency & Rate Limiting: Configure per-user and per-account limits to protect your resources.
  6. Admin Dashboard: Provides an intuitive Web UI for real-time monitoring and management.

Quick Start

Method 1: One-Click Script Installation (Recommended)

Recommended for clean Ubuntu/Debian systems:

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

Notes:

  • Requires PostgreSQL 15+ and Redis 7+ to be pre-installed.
  • The script installs the binary to /opt/sub2api and creates a systemd service.

Method 2: Docker Compose Deployment

# Create deployment directory
mkdir -p sub2api-deploy && cd sub2api-deploy

# Download and run deployment preparation script
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# Spin up services
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Once installed, access the admin dashboard at http://YOUR_SERVER_IP:8080.

Detailed Analysis

Architecture: Why is this more than just a Reverse Proxy?

The design priority of Sub2API is "Account State Management." Traditional reverse proxy tools (like Nginx) lack the ability to understand application-layer sessions.

  1. Sticky Sessions: For tools like Claude Code that require context continuity, Sub2API uses the session_id in the Header to lock a request to a specific upstream account, ensuring conversations aren't interrupted by account switching.

Note: If using Nginx as a reverse proxy, ensure underscores_in_headers on; is enabled to support session headers.

  1. Pooling Logic:
    The system abstracts multiple accounts into a single "resource pool." When one account hits a Rate Limit, the scheduler automatically routes traffic away from it, maximizing uptime.

  2. Integrated Ecosystem:
    While most relay tools require an external payment gateway, Sub2API’s built-in integration significantly reduces the operational complexity for small teams or community-led "carpools."

Technical Stack

  • Backend: Go ensures high concurrency handling and ease of deployment.
  • Database: PostgreSQL handles complex relationships and billing records.
  • Cache: Redis manages rate limiting and real-time state synchronization.

Address and Resources

Official Resources

Target Audience

  • Carpool Leads: Organizers looking to split the cost of Claude/OpenAI Plus.
  • Developers / Power Users: Individuals wanting to consolidate multiple account quotas for native CLI tools.
  • Internal Enterprise Teams: Teams needing to distribute and audit AI resource usage internally.

Summary and Outlook

Key Takeaways

  1. Clear Focus: Specialized in converting subscription-based quotas into standard API services.
  2. All-in-One: A closed-loop for management, scheduling, billing, and payments.
  3. Deployment Friendly: Multiple options including script-based and Docker-based setups.
  4. Reliable Performance: Built on a solid Go/PostgreSQL/Redis foundation suitable for medium-to-large distribution.

One-Sentence Review

Sub2API is currently the most tightly integrated open-source solution combining "resource aggregation" with a "commercial model," making it a powerful tool for achieving "subscription freedom."

Visit my homepage for more useful insights and interesting products.

Top comments (0)