La gestion mutualisée des abonnements d’intelligence artificielle pose un défi technique récurrent. Les équipes dispersent leurs dépenses sur des comptes isolés pour Claude, OpenAI, Gemini ou Grok sans visibilité globale. Sub2API unifie ces accès sous la forme d’une passerelle API open source.
Cette plateforme redistribue les quotas d’abonnements en centralisant l’authentification, la facturation à l’usage, l’équilibrage de charge et la redirection des requêtes entrantes vers les fournisseurs en amont.
Avertissements Légaux et Précautions d’Usage :
- Risque lié aux Conditions d’Utilisation : L’exploitation de ce projet peut enfreindre les conditions de service d’Anthropic et d’autres fournisseurs en amont. L’utilisateur assume l’entière responsabilité des risques découlant de cette utilisation.
- Conformité Réglementaire : L’outil requiert un usage conforme aux lois en vigueur dans votre juridiction. Toute utilisation illicite demeure proscrite.
- Clause de Non-Responsabilité : Ce code source sert des objectifs d’apprentissage et de recherche technique. Les auteurs déclinent toute responsabilité en cas de bannissement de compte, d’interruption de service ou de perte de données.
- Absence d’Autorisation Commerciale : Les développeurs n’accordent aucune licence d’exploitation commerciale. Les litiges et responsabilités juridiques incombent aux tiers initiateurs d’opérations commerciales.
Architecture Technique et Écosystème
L’infrastructure repose sur un socle performant :
| Composant | Choix Technologique |
|---|---|
| Backend | Go 1.26.5, Gin, Ent |
| Frontend | Vue 3.4+, Vite 5+, TailwindCSS |
| Base de Données | PostgreSQL 15+ |
| Cache et Files d’Attente | Redis 7+ |
L’écosystème comprend deux extensions majeures :
- Sub2ApiPay : Système de paiement en libre-service intégré. Il prend en charge Stripe, WeChat Pay, Alipay et EasyPay sans service tiers additionnel pour recharger le solde utilisateur.
- sub2api-mobile : Console d’administration mobile multiplateforme développée avec Expo et React Native (iOS, Android, Web) pour piloter utilisateurs, comptes et surveillance de trafic.
Fonctionnalités Principales
- Gestion Multi-Comptes : Prise en charge des comptes amonts OAuth et clés API traditionnelles.
- Distribution de Clés API : Génération de clés d’accès sur mesure pour vos utilisateurs finaux.
- Facturation Granulaire : Suivi de la consommation au jeton près et calcul financier automatisé.
- Routage Intelligent : Sélection d’infrastructure avec sessions persistantes (sticky sessions).
- Contrôle de Concomitance : Plafonds configurables par utilisateur et par compte.
- Limitation de Débit : Seuils stricts par volume de requêtes et par flux de jetons.
- Groupes Composites : Couche d’aiguillage administrateur qui résout les modèles demandés vers des fournisseurs physiques.
- Intégration Externe : Intégration de modules tiers (systèmes de tickets) via balises iframe dans l’interface d’administration.
Arborescence du Projet
sub2api/
├── backend/ # Service backend en Go
│ ├── cmd/server/ # Point d'entrée de l'exécutable
│ ├── internal/ # Modules internes
│ │ ├── config/ # Gestion de la configuration
│ │ ├── model/ # Modèles de données Ent
│ │ ├── service/ # Logique métier
│ │ ├── handler/ # Gestionnaires HTTP
│ │ └── gateway/ # Cœur de la passerelle API
│ └── resources/ # Ressources statiques
│
├── frontend/ # Interface utilisateur Vue 3
│ └── src/
│ ├── api/ # Appels API clients
│ ├── stores/ # Gestion d'état
│ ├── views/ # Vues et écrans
│ └── components/ # Composants réutilisables
│
└── deploy/ # Fichiers d'orchestration
├── docker-compose.yml # Configuration Docker Compose standard
├── .env.example # Gabarit des variables d'environnement
├── config.example.yaml # Exemple exhaustif de configuration YAML
└── install.sh # Script d'installation automatiséePrérequis Réseau Nginx
L’utilisation de Nginx en proxy inverse devant Sub2API (ou Codex CLI) exige l’activation des en-têtes avec tirets bas dans le bloc http :
underscores_in_headers on;Nginx élimine par défaut les en-têtes contenant un tiret bas tel que session_id. Ce comportement brise l’aiguillage des sessions persistantes.
Méthodes de Déploiement
1. Installation par Script (Linux amd64 / arm64)
Cette approche télécharge les binaires précompilés depuis GitHub Releases pour configurer un service systemd géré par l’OS :
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bashLe script inspecte l’architecture machine, installe le binaire dans /opt/sub2api, génère les unités de service et applique les permissions requises.
Initialisation du service :
sudo systemctl start sub2api
sudo systemctl enable sub2apiL’assistant de configuration web s’ouvre sur http://IP_SERVEUR:8080 pour lier PostgreSQL, Redis et créer le premier compte administrateur.
Commandes d’exploitation du service :
# Vérification de l'état sudo systemctl status sub2apiConsultation des journaux sudo journalctl -u sub2api -f Redémarrage du serveur sudo systemctl restart sub2api Désinstallation complètecurl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash -s -- uninstall -y
2. Déploiement avec Docker Compose (Méthode Recommandée)
Déploiement conteneurisé intégrant PostgreSQL et Redis :
# Création du répertoire dédié mkdir -p sub2api-deploy && cd sub2api-deployExécution du script de préparation curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash Lancement des conteneurs docker compose up -d Surveillance des journauxdocker compose logs -f sub2api
Pour un déploiement manuel sans le script d’amorce :
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
cp .env.example .env
chmod 600 .envGénérez vos secrets cryptographiques :
openssl rand -hex 32 # Pour JWT_SECRET
openssl rand -hex 32 # Pour TOTP_ENCRYPTION_KEY
openssl rand -hex 32 # Pour POSTGRES_PASSWORDRenseignez ces valeurs dans votre fichier .env :
POSTGRES_PASSWORD=votre_mot_de_passe_robuste
JWT_SECRET=votre_secret_jwt
TOTP_ENCRYPTION_KEY=votre_cle_totp
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=mot_de_passe_admin
SERVER_PORT=8080Création des répertoires de données locaux et lancement :
mkdir -p data postgres_data redis_data
docker compose -f docker-compose.local.yml up -dComparatif des modes de stockage conteneurisés :
| Version de Fichier | Stockage Données | Migration Serveur | Cas d’Usage |
|---|---|---|---|
| docker-compose.local.yml | Dossiers locaux | Sauvegarde par archive tar | Production, sauvegardes régulières |
| docker-compose.yml | Volumes Docker nommés | Commandes Docker spécifiques | Environnements de test simples |
Procédure de migration de serveur (version dossiers locaux) :
# Sur le serveur source docker compose -f docker-compose.local.yml down cd .. tar czf sub2api-complete.tar.gz sub2api-deploy/ scp sub2api-complete.tar.gz user@nouveau-serveur:/opt/Sur le nouveau serveurtar xzf sub2api-complete.tar.gz
cd sub2api-deploy/
docker compose -f docker-compose.local.yml up -d
3. Déploiement Apple Container (macOS)
Les stations Apple Silicon sous macOS 26 exécutent la pile complète avec Apple container 1.1.0+ :
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
./apple-container.sh init
./apple-container.sh up
./apple-container.sh status4. Compilation depuis les Sources
Exigences : Go 1.21+, Node.js 18+, PostgreSQL 15+, Redis 7+.
# 1. Récupération du dépôt git clone https://github.com/Wei-Shaw/sub2api.git cd sub2api2. Construction de l'interface graphique npm install -g pnpm
cd frontend
pnpm install
pnpm run build 3. Compilation du binaire Go intégrant le frontendcd ../backend
VERSION="$(./scripts/resolve-version.sh)"
go build -tags embed -ldflags="-X main.Version=${VERSION}" -o sub2api ./cmd/server
Avertissement Compte Administrateur Initial : L’assistant d’installation web crée le compte administrateur lors du premier démarrage si aucun fichier
config.yamln’existe. Si vous générezconfig.yamlavant le premier lancement, l’assistant reste inactif et la table utilisateur demeure vide. Écartez temporairement le fichier pour laisser l’assistant initialiser votre compte administrateur :mv config.yaml config.yaml.bak ./sub2api # Exécutez l'assistant sur http://localhost:8080 # Stoppez le processus (Ctrl+C) mv config.yaml.bak config.yaml ./sub2api # Relancez en production
Sécurité Réseau et Paramètres Avancés
Le fichier config.yaml centralise les directives de sécurité :
server: host: "0.0.0.0" port: 8080 mode: "release" trusted_proxies: ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]database:
host: "localhost"
port: 5432
user: "postgres"
password: "votre_password"
dbname: "sub2api" redis:
host: "localhost"
port: 6379 jwt:
secret: "chaine-aleatoire-securisee"
expire_hour: 24 default:
user_concurrency: 5
user_balance: 0
api_key_prefix: "sk-"
rate_multiplier: 1.0security:
url_allowlist:
enabled: true
allow_insecure_http: false
allow_private_hosts: false
response_headers:
enabled: true
csp:
enabled: true
trust_forwarded_ip_for_api_key_acl: false
billing:
circuit_breaker: true
En production, désactivez allow_insecure_http sous peine d’interception de clés en clair par attaque de l’homme du milieu (MITM) :
SECURITY_URL_ALLOWLIST_ENABLED=false
SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=falseUne tentative de transmission non chiffrée renvoie le rejet : Invalid base URL: invalid url scheme: http.
Gestion des en-têtes IP transmises par CDN tiers :
SECURITY_FORWARDED_CLIENT_IP_HEADERS=True-Client-IP,X-CDN-Client-IPJusqu’à 16 en-têtes sont prises en compte lorsque le mode hérité reste actif. En mode durci, Gin utilise server.trusted_proxies.
Limites WebSocket et Mode Simple
Les flux WebSocket pour les réponses OpenAI sont bornés par des verrous distribués coordonnés dans Redis sous un bail de 60 secondes rafraîchi toutes les 20 secondes :
gateway:
openai_ws:
client_first_message_timeout_seconds: 30
ingress_inter_turn_idle_timeout_seconds: 300
max_ingress_connections_per_api_key: 64
mode_router_v2_enabled: trueLe paramètre http_bridge permet de transformer le flux WebSocket client en requêtes HTTP amonts en cas d’instabilité du réseau du fournisseur.
Le Simple Mode désactive le système de facturation pour un usage personnel :
RUN_MODE=simple
SIMPLE_MODE_CONFIRM=trueGestion des Tâches Asynchrones d’Images
Les générations d’images lourdes s’exécutent via les routes asynchrones :
POST /v1/images/generations/asyncPOST /v1/images/edits/async- Interrogation de l’état :
GET /v1/images/tasks/{task_id}
Intégration Approfondie de Grok / xAI
Sub2API prend en charge les comptes d’abonnement Grok via OAuth xAI et les clés API directes. Les requêtes sont traduites selon les formats cibles :
- Endpoints Réponses Publiques :
/v1/responses,/responses,/backend-api/codex/responses - Endpoint Compatible Claude :
/v1/messages(converti en réponses xAI et retourné sous le format de messages Anthropic) - Chat Completions :
/v1/chat/completions,/chat/completions - Modèles Textuels :
grok-4.5,grok-4.3,grok-build-0.1,grok-composer-2.5-fast,grok-4.20-0309-reasoning,grok-4.20-0309-non-reasoning,grok-4.20-multi-agent-0309 - Modèles Médias :
grok-imagine,grok-imagine-image-quality,grok-imagine-image,grok-imagine-image-2.0,grok-imagine-edit,grok-imagine-video,grok-imagine-video-1.5
Configuration de Grok CLI via ~/.grok/config.toml :
[models]
default = "grok"
web_search = "grok"
[model."grok"]model = “grok-4.5”
base_url = “https://votre-sub2api.example.com/v1”
name = “Grok 4.5”
api_key = “sk-votre-cle-sub2api”
api_backend = “responses”
context_window = 1000000
supports_backend_search = true
Contrôle de validation du client :
grok inspect
grok -p "Reply with sub2api-ok" -m grokGestion de l’éligibilité média : Les comptes OAuth nécessitent une validation de facturation positive. Les comptes sans souscription active reçoivent une réponse HTTP 503 avec le code grok_media_no_eligible_account. Un administrateur peut forcer l’éligibilité d’un compte via l’API en renseignant extra.grok_media_eligible = true.
Prise en Charge des Comptes Antigravity
Les comptes Antigravity disposent de passerelles dédiées :
| Point d’Entrée Dédié | Modèles Cibles |
|---|---|
/antigravity/v1/messages | Modèles Claude |
/antigravity/v1beta/ | Modèles Gemini |
Configuration pour Claude Code :
export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"Avertissement Contexte de Session : Les contextes conversationnels d’Anthropic Claude et d’Antigravity Claude sont incompatibles. Isolez impérativement ces modèles au sein de groupes distincts pour empêcher toute corruption de session.