BoosAPI/README_EN.md

BoosAPI

AI Aggregation Gateway + Built-in ComfyUI — Unify scattered relay stations into one entry point

Aggregate your New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API stations
into one API Key, one endpoint — with auto model discovery, smart routing, and cost optimization.
Built-in ComfyUI chat assistant — generate images/videos from natural language, ready out of the box.
SaaS multi-tenant architecture — organization management, member invitations, plan limits.

中文 | English

---

📖 Introduction

With the growing ecosystem of AI relay stations (New API / One API based), managing balances, models, and API keys across multiple stations is tedious and time-consuming.

BoosAPI acts as a meta-aggregation layer above these stations, unifying them under a single entry point — all downstream tools connect seamlessly without configuration changes.

Supported Upstreams

• Panels: New API, One API, OneHub, DoneHub, Veloera, AnyRouter, Sub2API
• Generic: OpenAI / Claude / Gemini compatible, cliproxyapi / CPA
• Official: Aliyun, Zhipu, Doubao Coding Plan, DeepSeek, Moonshot, MiniMax, ModelScope
• OAuth: Codex, Claude, Gemini CLI, Antigravity

Pain Point	BoosAPI Solution
🔑 One key per station, messy configs	Unified proxy entry + multi-key strategy
💸 Which station is cheapest?	Smart routing by cost, balance, usage
🔄 Manual failover	Auto failover with cooldown and retry
📊 Scattered balances	Central dashboard with alerts
✅ Daily check-ins	Auto check-in with reward tracking
🤷 What models are available?	Auto model discovery, zero config
🎨 ComfyUI workflows too complex?	Chat assistant, describe in natural language
👥 Need multi-user access?	Organizations, member invites, role-based access
📋 Different teams need quotas?	Plan system, Free/Pro/Enterprise tiers

---

✨ Features

🎨 Built-in ComfyUI Chat Assistant

• Natural language to workflow: describe what you want, AI builds the ComfyUI pipeline
• Multi-view generation: front/back/left/right directional image generation
• Scene/video generation: text description directly generates video content
• SSE real-time streaming: generation progress feedback
• Sidebar "Chat Assistant" entry, same UI as the aggregation gateway
• Auto-connects to ComfyUI API (:8188), zero configuration required

🌐 Unified Proxy Gateway

• Compatible with OpenAI and Claude downstream formats
• Responses / Chat Completions / Messages / Completions / Embeddings / Images / Models / Files
• SSE streaming with automatic format conversion

🧠 Smart Routing Engine

• Auto-discovers models from all upstream stations
• Four-tier cost signals: measured → configured → catalog → fallback
• Multi-channel weighted distribution (cost 40%, balance 30%, usage 30%)
• Auto cooldown on failure (default 10 min), seamless channel switching

📡 Multi-Platform Management

Platform	Adapter
New API	new-api
One API	one-api
OneHub	onehub
DoneHub	done-hub
Veloera	veloera
AnyRouter	anyrouter
Sub2API	sub2api

👥 Account & Token Management

• Multi-station, multi-account with health tracking (healthy / unhealthy / degraded / disabled)
• Encrypted credential storage, auto-renewal, cascading disable

💰 Balance Management

• Scheduled refresh (default hourly), income/expense trends
• Fallback estimation when API is unavailable

👥 SaaS Multi-Tenant

• Organizations: Create orgs, each with independent members and quotas
• Member Invitations: Email-based invites with admin/member roles
• Three Plans: Free (3 members) / Pro (10) / Enterprise (100)
• Role Control: Owner / Admin / Member with granular permissions
• Plan Enforcement: Auto-limit members, API keys, daily requests
• Invite Links: Token-based, 48h expiry

🔔 Alerts & Notifications

Five channels: Webhook / Bark / ServerChan / Telegram Bot / SMTP

Scenarios: low balance, station failure, check-in failure, proxy errors, token expiry, daily digest

🔌 REST API Overview

Endpoint	Method	Description
/api/organizations	GET/POST	List / Create org
/api/organizations/plans	GET	List available plans
/api/organizations/:id	GET/PATCH	Org detail / Update
/api/organizations/:id/members	GET	List members
/api/organizations/:id/members/:uid	PATCH/DELETE	Change role / Remove
/api/organizations/:id/invitations	GET/POST	List / Create invite
/api/organizations/:id/invitations/:invId	DELETE	Cancel invite
/api/invitations/:token	GET	Public invite lookup
/api/invitations/:token/accept	POST	Accept invitation
/api/users/register	POST	Register new user
/api/users/login	POST	Login (returns JWT)
/api/users/me	GET/PATCH	Profile / Update
/api/user-api-keys	GET/POST	List / Create API key

---

🚀 Quick Start

Docker Compose (Recommended)

mkdir boosapi && cd boosapi

cat > docker-compose.yml << 'EOF'
services:
  boosapi:
    image: 1467078763/metapi:latest
    ports:
      - "4000:4000"
    volumes:
      - ./data:/app/data
    environment:
      AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required}
      PROXY_TOKEN: ${PROXY_TOKEN:?PROXY_TOKEN is required}
      CHECKIN_CRON: "0 8 * * *"
      BALANCE_REFRESH_CRON: "0 * * * *"
      PORT: ${PORT:-4000}
      DATA_DIR: /app/data
      TZ: ${TZ:-Asia/Shanghai}
    restart: unless-stopped
EOF

export AUTH_TOKEN=your-admin-token
export PROXY_TOKEN=your-proxy-sk-token
docker compose up -d

Open http://localhost:4000 and log in with AUTH_TOKEN.

---

🏗️ Tech Stack

Layer	Tech
Backend	Fastify
Frontend	React 18 + Vite
Language	TypeScript
Styling	Tailwind CSS v4
Database	SQLite / MySQL / PostgreSQL + Drizzle ORM
Visualization	VChart
Container	Docker + Docker Compose
Test	Vitest

---

🛠️ Local Development

npm install
npm run db:migrate
npm run dev

npm run build        # Build web + server
npm test             # Run tests

---

📜 License

MIT