BossAI

Bring together all your New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API sites
into one API Key, one endpoint, with automatic model discovery, smart routing, and cost optimization.

中文 | English

Docs · Quick Start · Deployment · Configuration · FAQ · Contributing

About

The AI ecosystem is seeing a growing number of aggregation relay stations based on New API / One API and similar projects. Managing balances, model lists, and API keys across multiple sites is scattered and time-consuming.

Metapi acts as the Meta-Aggregation Layer on top of these relay stations, unifying multiple sites into one endpoint (with configurable per-project downstream API Keys) — all downstream tools (Cursor, Claude Code, Codex, Open WebUI, etc.) can seamlessly access all models. Currently supported upstream platforms:

New API
One API
OneHub
DoneHub
Veloera
AnyRouter — Universal routing platform
Sub2API — Subscription-based relay

Pain Point	How Metapi Solves It
One key per site, tedious client config	Unified proxy endpoint + optional per-project downstream keys — all site models auto-aggregated under `/v1/*`
No idea which site offers the cheapest model	Smart routing auto-selects the optimal channel by cost, balance, and usage
Site goes down, manual switching is a hassle	Auto-failover — failed channels cool down and traffic shifts automatically
Balances scattered everywhere	Centralized dashboard — at-a-glance overview with low-balance alerts
Daily check-ins across sites	Auto check-in — scheduled execution with reward tracking
Don't know which site has which models	Auto model discovery — new upstream models appear with zero config

Screenshots

Dashboard — Balance distribution, spending trends, system overview	Model Marketplace — Cross-site model coverage, pricing comparison, measured metrics
Smart Routing — Multi-channel probability distribution, cost-priority routing	Account Management — Multi-site multi-account, health state tracking
Site Management — Upstream site configuration and status overview	Token Management — API Token lifecycle management
Model Playground — Interactive online model testing	Check-in Log — Auto check-in status and reward tracking
Usage Logs — Proxy request logs and cost breakdown	Availability Monitor — Channel health real-time monitoring
System Settings — Global parameters and security configuration	Notification Settings — Multi-channel alert and push configuration

Architecture Overview

Downstream Clients (Cursor · Claude Code · Codex · Open WebUI · Cherry Studio, etc.) ↓ Authorization: Bearer <PROXY_TOKEN> Metapi Gateway • Unified /v1 proxy for core OpenAI / Claude-compatible endpoints (Responses, Chat Completions, Messages, Completions, Embeddings, Images, Models) • Smart Routing Engine — weighted selection by cost, balance, and availability; auto-cooldown & retry on failure • Model Discovery — auto-aggregates all upstream models with zero config • Format Conversion — transparent bidirectional OpenAI ⇄ Claude conversion • Auto Check-in · Balance Management · Alerts & Notifications · Data Dashboard ↓ Upstream Platforms (New API · One API · OneHub · DoneHub · Veloera · AnyRouter · Sub2API …)

Features

Unified Proxy Gateway

Compatible with OpenAI and Claude downstream formats, works with all mainstream clients
Supports Responses / Chat Completions / Messages / Completions (Legacy) / Embeddings / Images / Models (current core coverage)
Full SSE streaming support with automatic format conversion (OpenAI <-> Claude)

Smart Routing Engine

Auto-discovers all available models from upstream sites — zero-config route table generation
Four-tier cost signal: measured cost -> account-configured cost -> catalog reference price -> default fallback
Multi-channel probabilistic distribution weighted by cost (40%), balance (30%), and usage (30%)
Failed channels auto-cool down (default 10-minute cooldown)
Auto-retry on failure with automatic channel switching
Routing decisions are visually explainable — every choice is transparent and auditable

_{Smart Routing UI — supports exact match, wildcards, probability distribution, and more routing strategies}

Multi-Platform Aggregation

Platform	Adapter	Description
New API	`new-api`	Next-gen LLM gateway
One API	`one-api`	Classic OpenAI API aggregation
OneHub	`onehub`	Enhanced One API fork
DoneHub	`donehub`	Enhanced OneHub fork
Veloera	`veloera`	API gateway platform
AnyRouter	`anyrouter`	Universal routing platform
Sub2API	`sub2api`	Subscription-based relay

Each adapter supports: account login, balance queries, model enumeration, token sync, daily check-in, user info retrieval, and full lifecycle management.

Account & Token Management

Multi-site, multi-account: Each site supports multiple accounts, each account can hold multiple API tokens
Health tracking: healthy / unhealthy / degraded / disabled four-state machine
Encrypted credential storage: All sensitive credentials are encrypted in the local database
Auto-renewal: Tokens are automatically re-authenticated when expired
Cascading control: Disabling a site automatically disables all associated accounts

Model Marketplace

Cross-site model coverage overview: which models are available, how many accounts cover them, pricing comparison
Latency, success rate, and other measured metrics
Upstream model catalog caching with brand classification (OpenAI, Anthropic, Google, DeepSeek, etc.)
Interactive model tester for online verification

_{Model Marketplace — browse all available models' coverage, pricing, and performance metrics in one place}

Auto Check-in

Cron-scheduled automatic check-in (default: daily at 08:00)
Smart reward parsing with failure notifications
Per-account execution with enable/disable control
Full check-in logging with history queries
Concurrency locking to prevent duplicate check-ins

Balance Management

Scheduled balance refresh (default: every hour), batch updates for all active accounts
Income tracking: daily/cumulative income with spending trend analysis
Balance fallback estimation: infer balance changes from proxy logs when API is unavailable
Auto re-login on credential expiry

Alerts & Notifications

Five notification channels supported:

Channel	Description
Webhook	Custom HTTP push
Bark	iOS push notifications
ServerChan	WeChat notifications
Telegram Bot	Telegram message notifications
SMTP Email	Standard email notifications

Alert scenarios: low balance warning, site/account anomalies, check-in failures, proxy request failures, token expiry reminders, daily summary reports. Alert cooldown mechanism (default: 300 seconds) prevents duplicate notifications.

Data Dashboard

Site balance pie chart, daily spending trend graphs
Global search (sites, accounts, models)
System event logs, proxy request logs (model, status, latency, token usage, cost estimation)

_{Data Dashboard — balance distribution, spending trends, system health at a glance}

Model Playground

Interactive chat testing to instantly verify model availability and response quality
Select any routed model to compare outputs across different channels
Streaming / non-streaming dual mode testing

_{Model Playground — interactive online testing, verify model availability and response quality}

Lightweight Deployment

Single Docker container with built-in SQLite — no external dependencies
Alpine base image, minimal footprint
Full data import/export for worry-free migration

Quick Start

Docker Compose (Recommended)

mkdir metapi && cd metapi

cat > docker-compose.yml << 'EOF'
services:
  metapi:
    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

# Set tokens and start
# AUTH_TOKEN = Admin panel login token (enter this value when logging in)
export AUTH_TOKEN=your-admin-token
# PROXY_TOKEN = Token for downstream clients to call /v1/*
export PROXY_TOKEN=your-proxy-sk-token
docker compose up -d

One-line Docker command

docker run -d --name metapi \
  -p 4000:4000 \
  -e AUTH_TOKEN=your-admin-token \
  -e PROXY_TOKEN=your-proxy-sk-token \
  -e TZ=Asia/Shanghai \
  -v ./data:/app/data \
  --restart unless-stopped \
  1467078763/metapi:latest

After starting, visit http://localhost:4000 and log in with your AUTH_TOKEN!

Important

Make sure to change AUTH_TOKEN and PROXY_TOKEN — do not use default values. Data is stored in the ./data directory and persists across upgrades.

Tip

The initial admin token is the AUTH_TOKEN configured at startup. If running outside Compose without explicitly setting AUTH_TOKEN, the default is change-me-admin-token (for local debugging only). If you change the admin token in the Settings panel, use the new token for subsequent logins.

Release Package (Linux / macOS / Windows)

If you prefer not to use Docker, download a pre-built Release package:

Go to Releases and download the archive for your platform
Extract and enter the directory
Set environment variables and start

Linux / macOS:

export AUTH_TOKEN=your-admin-token
export PROXY_TOKEN=your-proxy-sk-token
export PORT=4000
export DATA_DIR=./data
./start.sh

Windows (PowerShell):

$env:AUTH_TOKEN="your-admin-token"
$env:PROXY_TOKEN="your-proxy-sk-token"
$env:PORT="4000"
$env:DATA_DIR="./data"
.\start.bat

start.sh / start.bat will:

Check whether better-sqlite3 matches the current Node.js ABI
If ABI mismatch is detected, automatically run npm rebuild better-sqlite3
If rebuild fails, fall back to npm ci --omit=dev to reinstall runtime dependencies
Then run database migrations and start the service

Note

The Release package requires Node.js installed locally (supports 20+, recommends 22 LTS).
If your local Node major version differs from the one used during packaging (for example, package built with Node 22 while local is Node 24), first startup may trigger automatic rebuild and requires network access.

Upgrade

docker compose pull && docker compose up -d && docker image prune -f

For more deployment options, see Deployment Guide.

Documentation

Docs site (VitePress) local preview:
npm run docs:dev
Docs site build:
npm run docs:build
GitHub Actions auto publish: each push to main runs .github/workflows/docs-pages.yml and deploys to GitHub Pages. First-time setup in repository settings: Settings -> Pages -> Build and deployment -> Source: GitHub Actions

Category	Link	Description
Docs Home	docs/index.md	Publishable docs portal with nav/sidebar/search
Overview	docs/README.md	Documentation index
Quick Start	docs/getting-started.md	Get running in 10 minutes
Deployment	docs/deployment.md	Docker Compose, reverse proxy, upgrades
Configuration	docs/configuration.md	All environment variables and routing params
Client Integration	docs/client-integration.md	Open WebUI / Cherry Studio / Cursor, etc.
Operations	docs/operations.md	Backup, logging, health checks
FAQ	docs/faq.md	Common errors and fixes
FAQ/Tutorial Contribution	docs/community/faq-tutorial-guidelines.md	Templates and workflow for community knowledge

Environment Variables

Basic Configuration

Variable	Description	Default
`AUTH_TOKEN`	Admin panel login token (must change)	`change-me-admin-token`
`PROXY_TOKEN`	Proxy API Bearer Token (must change)	`change-me-proxy-sk-token`
`PORT`	Service listening port	`4000`
`DATA_DIR`	Data directory (SQLite database)	`./data`
`TZ`	Timezone	`Asia/Shanghai`
`ACCOUNT_CREDENTIAL_SECRET`	Account credential encryption key	Defaults to `AUTH_TOKEN`

Scheduled Tasks

Variable	Description	Default
`CHECKIN_CRON`	Auto check-in cron expression	`0 8 * * *`
`BALANCE_REFRESH_CRON`	Balance refresh cron expression	`0 * * * *`

Smart Routing Parameters

Variable	Description	Default
`ROUTING_FALLBACK_UNIT_COST`	Default unit price when no cost signal	`1`
`BASE_WEIGHT_FACTOR`	Base weight factor	`0.5`
`VALUE_SCORE_FACTOR`	Value score factor	`0.5`
`COST_WEIGHT`	Cost weight in routing selection	`0.4`
`BALANCE_WEIGHT`	Balance weight in routing selection	`0.3`
`USAGE_WEIGHT`	Usage weight in routing selection	`0.3`

Notification Channel Configuration

Variable	Description	Default
`WEBHOOK_ENABLED`	Enable Webhook notifications	`true`
`WEBHOOK_URL`	Webhook push URL	empty
`BARK_ENABLED`	Enable Bark push	`true`
`BARK_URL`	Bark push URL	empty
`SERVERCHAN_ENABLED`	Enable ServerChan notifications	`true`
`SERVERCHAN_KEY`	ServerChan SendKey	empty
`SMTP_ENABLED`	Enable email notifications	`false`
`SMTP_HOST`	SMTP server address	empty
`SMTP_PORT`	SMTP port	`587`
`SMTP_SECURE`	Use SSL/TLS	`false`
`SMTP_USER` / `SMTP_PASS`	SMTP authentication	empty
`SMTP_FROM` / `SMTP_TO`	Sender / recipient	empty
`NOTIFY_COOLDOWN_SEC`	Same-alert cooldown (seconds)	`300`

Security Configuration

Variable	Description	Default
`ADMIN_IP_ALLOWLIST`	Admin API IP allowlist (comma-separated)	empty (no restriction)

Full configuration reference: docs/configuration.md

Proxy API Endpoints

Metapi exposes standard OpenAI / Claude compatible endpoints:

Endpoint	Method	Description
`/v1/responses`	POST	OpenAI Responses
`/v1/chat/completions`	POST	OpenAI Chat Completions
`/v1/messages`	POST	Claude Messages
`/v1/completions`	POST	OpenAI Completions (Legacy)
`/v1/embeddings`	POST	Embeddings
`/v1/images/generations`	POST	Image Generation
`/v1/models`	GET	List all available models

Include Authorization: Bearer <PROXY_TOKEN> in request headers.

The global PROXY_TOKEN works by default. From System Settings -> Downstream API Key Strategy you can create multiple project-level downstream keys with individual configuration:

Expiration time (ExpireAt)
Cost and request limits (MaxCost / MaxRequests)
Model allowlist (SupportedModels, supports exact/glob/re:regex)
Route allowlist (AllowedRouteIds)
Site weight multipliers (SiteWeightMultipliers, control per-project upstream preference ratios)

Client Integration

Compatible with all OpenAI API-compatible clients:

Setting	Value
Base URL	`https://your-domain.com` (clients usually append `/v1` automatically)
API Key	Your configured `PROXY_TOKEN`
Model List	Auto-fetched from `GET /v1/models`

CLI Quick Setup (Claude Code / Codex)

Claude Code (`~/.claude/settings.json`)

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-domain.com",
    "ANTHROPIC_API_KEY": "your-proxy-sk-token",
    "ANTHROPIC_AUTH_TOKEN": "your-proxy-sk-token",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Note: Different client versions may read ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN; setting both is recommended.

Codex (`~/.codex/config.toml` + `~/.codex/auth.json`)

~/.codex/config.toml

model = "gpt-5"
model_provider = "metapi"

[model_providers.metapi]
name = "metapi"
base_url = "https://your-domain.com/v1"

~/.codex/auth.json

{
  "OPENAI_API_KEY": "your-proxy-sk-token"
}

Tip: model must exist in Metapi GET /v1/models.

Verified Compatible Clients

ChatGPT-Next-Web
Open WebUI
Cherry Studio
Cursor
Claude Code
Codex CLI
Roo Code
Kilo Code
And any client that supports the OpenAI API format

Troubleshooting: Streaming Response Issues

If non-streaming works but streaming fails, check:

Whether the reverse proxy has SSE buffering disabled (Nginx: proxy_buffering off)
Whether a middleware layer is rewriting the text/event-stream Content-Type
Whether the client requires a specific streaming format

Nginx reference configuration:

location / {
    proxy_pass http://127.0.0.1:4000;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding off;
}

For detailed integration instructions: docs/client-integration.md

Tech Stack

Layer	Technology
Backend	Fastify — High-performance Node.js framework
Frontend	React 18 + Vite
Language	TypeScript — End-to-end type safety
Styling	Tailwind CSS v4 — Utility-first CSS framework
Database	SQLite (better-sqlite3) + Drizzle ORM
Charts	VChart (@visactor/react-vchart)
Scheduling	node-cron
Containerization	Docker (Alpine) + Docker Compose
Testing	Vitest

Local Development

# Install dependencies
npm install

# Run database migrations
npm run db:migrate

# Start dev environment (frontend + backend hot reload)
npm run dev

npm run build          # Build frontend + backend
npm run build:web      # Build frontend only (Vite)
npm run build:server   # Build backend only (TypeScript)
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run db:generate    # Generate Drizzle migration files

Compatible Upstream Platforms

Project	Description
New API	Next-gen LLM gateway, one of Metapi's primary upstreams
One API	Classic OpenAI API aggregation
OneHub	Enhanced One API fork
DoneHub	Enhanced OneHub fork
Veloera	API gateway platform

Referenced & Used Projects

Project	Description
All API Hub	Browser extension — all-in-one relay account manager, Metapi's original inspiration
LLM Metadata	LLM model metadata library, used for model description reference
New API	Platform adapter reference implementation

Data & Privacy

Metapi is fully self-hosted. All data (accounts, tokens, routes, logs) is stored in the local SQLite database. No data is sent to any third party. Proxy requests are transmitted directly between your server and upstream sites only.

Contributing

All forms of contribution are welcome!

Report bugs — Submit an Issue
Feature suggestions — Start a Discussion
Code contributions — Submit a Pull Request
Contributing guide — CONTRIBUTING.md
Code of conduct — CODE_OF_CONDUCT.md

Security

If you discover a security issue, please refer to SECURITY.md and report it privately.

License

MIT

Star History

If Metapi helps you, a Star is the best support!

_{Built with love by the AI community}

Languages

TypeScript 66.3%

Rust 27.7%

CSS 4.5%

JavaScript 0.6%

Shell 0.5%

Other 0.3%

README_EN.md Unescape Escape