Sub2API is an open-source AI API gateway platform for distributing subscription quotas for AI products. Its core purpose is to let users access upstream AI services through API Keys generated by the platform. The platform handles authentication, billing, load balancing, and request forwarding, thereby unifying access to subscriptions such as Claude, OpenAI, Gemini, and Grok, and supporting ride-sharing to share costs.
Main capabilities include: multi-account management, supporting two upstream account types: OAuth and API Key; API Key distribution, which can generate and manage API Keys for users; precise billing, providing token-level usage tracking and cost calculation; intelligent scheduling, supporting intelligent account selection with sticky sessions; concurrency control, allowing per-user and per-account concurrency limits to be set; rate limiting, allowing request and token rate limits to be configured; a built-in payment system, supporting EasyPay, Alipay, WeChat Pay, and Stripe, allowing users to top up on their own without a separate payment service; an admin backend, providing a web interface for monitoring and management; composite grouping, where the administrator routing layer can resolve requested models to specific providers, suitable for multi-provider groups; external system integration, allowing external systems (such as ticketing systems) to be embedded via iframe to extend the admin backend.
In terms of usage, the project provides multiple deployment methods. Method one is script installation (recommended). The one-click script downloads precompiled binaries from GitHub Releases and requires a Linux server (amd64 or arm64), PostgreSQL 15+, Redis 7+, and root privileges; the script detects the system architecture, downloads the latest version, installs the binary to /opt/sub2api, creates a systemd service, and configures the system user and permissions, after which a setup wizard completes the database, Redis, and administrator account configuration. Method two is Docker Compose (recommended), including PostgreSQL and Redis containers, and can use an automated deployment script or manually configure the .env file, then access http://YOUR_SERVER_IP:8080 to proceed. Method three is Apple container (macOS), suitable for Apple silicon Macs running macOS 26, and requires Apple container 1.1.0 or later. Method four is building from source, for development or customization, and note that the -tags embed flag is used to embed the frontend.
Applicable scenarios include quick access for individual developers or internal teams (simple mode, set RUN_MODE=simple, hide SaaS-related features, and skip the billing process), multi-account ride-sharing, scenarios requiring unified management of multiple AI subscription quotas, scenarios requiring precise billing and payment integration, and handling long-running OpenAI/Grok image generation and editing through the asynchronous image task interface. Regarding Grok/xAI support, the platform supports Grok subscription accounts via xAI OAuth and standard xAI API-key accounts. Both forward OpenAI-compatible Responses traffic to xAI, supporting targets such as /v1/responses, /responses, /backend-api/codex/responses, /v1/messages, and /v1/chat/completions, as well as text models such as grok-4.5 and grok-4.3 and image and video generation targets.
Limitations and notes: using this project may violate the terms of service of upstream providers such as Anthropic, and users bear the risk themselves; the project is for technical learning and research only, and the author is not responsible for account bans, service interruptions, data loss, etc.; the developer has not authorized any commercial operation. Regarding security, when security.url_allowlist.enabled=false, the system allows HTTP URLs, and production environments should use only HTTPS; Nginx reverse proxies should note that headers containing underscores (such as session_id) are discarded by default, which may break sticky session routing; the initial administrator account is created only through the setup wizard, and default.admin_email/default.admin_password in config.yaml are not used to create the account; in a simple-mode production environment, SIMPLE_MODE_CONFIRM=true must be set to allow startup.
