A relay for relays — aggregate scattered AI relay stations into one unified gateway

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 · Client Integration · FAQ · Contributing

Try Metapi without deploying — full-featured demo instance:

⚠️ Security Notice: This is a public demo. Do NOT enter any real API keys, credentials, or site information. Data may be reset at any time.

ℹ️ Note: Demo runs on Render free tier + OpenRouter free models (only :free suffixed models available). First visit may take 30-60s to wake up.

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

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

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 …)

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

• 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}

Adapters cover shared capabilities such as model discovery, balance access, token management, and proxy integration; login, check-in, and user-info flows vary by platform.

• 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

• 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}

• 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

• 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

Five notification channels supported:

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.

• 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}

• 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}

• Single Docker container with a default local data directory, plus optional external MySQL / PostgreSQL runtime DB
• Docker images support amd64, arm64, and armv7l (linux/arm/v7) server deployments
• Full data import/export for worry-free migration

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

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!

For Docker Compose, desktop installers, reverse proxy, upgrades, and database options, see Deployment Guide.

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

Full configuration reference: docs/configuration.md

Metapi exposes standard OpenAI / Claude compatible endpoints:

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 (expiresAt)
• 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)

Compatible with all OpenAI API-compatible clients:

Standard OpenAI /v1/files workflows are also supported for clients that use the official file API.

For detailed per-client setup, examples, and troubleshooting, see docs/client-integration.md.

# 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 run dist:desktop:mac:intel # Build mac Intel (x64) desktop installer
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run db:generate    # Generate Drizzle migration files

Metapi is fully self-hosted. All data (accounts, tokens, routes, logs) stays in your own deployment environment. No data is sent to any third party. Proxy requests are transmitted directly between your server and upstream sites only.

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

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

MIT

Thanks to everyone who has contributed code, bug reports, ideas, and real-world feedback to Metapi. A lot of the product polish in this project came directly from community usage and iteration.

Special thanks to all contributors: