QuantumNous/new-api

📝 Project Description

[!IMPORTANT]

• This project is intended solely for lawful and authorized AI API gateway, organization-level authentication, multi-model management, usage analytics, cost accounting, and private deployment scenarios.
• Users must lawfully obtain upstream API keys, accounts, model services, and interface permissions, and must comply with upstream terms of service and applicable laws and regulations.
• Users should ensure their use complies with upstream terms of service and applicable laws and regulations.
• When providing generative AI services to the public, users should comply with applicable regulatory requirements and fulfill all filing, licensing, content safety, real-name verification, log retention, tax, and upstream authorization obligations required by their jurisdiction.

🤝 Trusted Partners

No particular order

🙏 Special Thanks

Thanks to JetBrains for providing free open-source development license for this project

🚀 Quick Start

Using Docker Compose (Recommended)

# Clone the project
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# Edit docker-compose.yml configuration
nano docker-compose.yml

# Start the service
docker-compose up -d

# Pull the latest image
docker pull calciumion/new-api:latest

# Using SQLite (default)
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

# Using MySQL
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

🎉 After deployment is complete, visit http://localhost:3000 to start using!

[!WARNING] When operating this project as a public generative AI service or API resale service, users should first complete all required filing, licensing, content safety, real-name verification, log retention, tax, payment, and upstream authorization obligations.

📖 For more deployment methods, please refer to Deployment Guide

📚 Documentation

Quick Navigation:

✨ Key Features

For detailed features, please refer to Features Introduction

🎨 Core Functions

💰 Authorized Usage Accounting and Billing

• ✅ Internal top-up and quota allocation for lawful authorized scenarios (EPay, Stripe)
• ✅ Organization-level per-request, usage-based, and cache-hit cost accounting
• ✅ Cache billing statistics for OpenAI, Azure, DeepSeek, Claude, Qwen, and supported models
• ✅ Flexible billing policies for internal management or authorized enterprise customers

🔐 Authorization and Security

• 😈 Discord authorization login
• 🤖 LinuxDO authorization login
• 📱 Telegram authorization login
• 🔑 OIDC unified authentication
• 🔍 Key quota query usage (with new-api-key-tool)

🚀 Advanced Features

API Format Support:

• ⚡ OpenAI Responses
• ⚡ OpenAI Realtime API (including Azure)
• ⚡ Claude Messages
• ⚡ Google Gemini
• 🔄 Rerank Models (Cohere, Jina)

Intelligent Routing:

• ⚖️ Channel weighted random
• 🔄 Automatic retry on failure
• 🚦 User-level model rate limiting

Format Conversion:

• 🔄 OpenAI Compatible ⇄ Claude Messages
• 🔄 OpenAI Compatible → Google Gemini
• 🔄 Google Gemini → OpenAI Compatible - Text only, function calling not supported yet
• 🚧 OpenAI Compatible ⇄ OpenAI Responses - In development
• 🔄 Thinking-to-content functionality

Reasoning Effort Support:

🤖 Model Support

For details, please refer to API Documentation - Gateway Interface

📡 Supported Interfaces

🚢 Deployment

[!TIP] Latest Docker image: calciumion/new-api:latest

📋 Deployment Requirements

⚙️ Environment Variable Configuration

🔧 Deployment Methods

# Clone the project
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# Edit configuration
nano docker-compose.yml

# Start service
docker-compose up -d

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

⚠️ Multi-machine Deployment Considerations

[!WARNING]

• All nodes must use the same primary database and the same SESSION_SECRET; otherwise Access Tokens, refresh sessions, and temporary authentication flows cannot be verified consistently.
• Nodes connected to the same Redis must also use the same CRYPTO_SECRET, or their cache-key digests will differ and shared entries cannot be reused consistently.

The database is authoritative for login Sessions and for the per-user active/issuance limits. Redis Session entries are short-lived caches whose TTL follows SYNC_FREQUENCY (60 seconds by default) and never exceeds the Session's remaining lifetime.

A shorter SYNC_FREQUENCY reduces the independent-Redis staleness window but causes one additional primary-key Session lookup per active SID, per node, per TTL. These guarantees make Session authentication bounded-stale across the supported topologies; rate limits and other Redis-backed control-plane caches remain topology-dependent.

See User authentication and login sessions for the token, Origin-check and PAT contracts.

🔄 Channel Retry and Cache

Retry configuration: Settings → Operation Settings → General Settings → Failure Retry Count

Cache configuration:

• REDIS_CONN_STRING: Redis cache (recommended)
• MEMORY_CACHE_ENABLED: Memory cache

🔗 Related Projects

Upstream Projects

Supporting Tools

💬 Help Support

📖 Documentation Resources

🤝 Contribution Guide

Welcome all forms of contribution!

• 🐛 Report Bugs
• 💡 Propose New Features
• 📝 Improve Documentation
• 🔧 Submit Code

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Additional terms under AGPLv3 Section 7 apply. Modified versions must preserve the author attribution notice Frontend design and development by New API contributors. in the appropriate legal notices and in any prominent about, legal, footer, or attribution location presented by the user interface.

Modified versions that present a user interface must also preserve a visible link to the original project: https://github.com/QuantumNous/new-api.

This is an open-source project developed based on One API (MIT License).

If your organization's policies do not permit the use of AGPLv3-licensed software, or if you wish to avoid the open-source obligations of AGPLv3, please contact us at: [email protected]

🌟 Star History