new-api/README.md

New API

🍥 Next-Generation LLM Gateway and AI Asset Management System

简体中文 | 繁體中文 | English | Français | 日本語

Quick Start • Key Features • Deployment • Documentation • Help

📝 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

Using Docker Commands

# 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

💡 Tip: -v ./data:/data will save data in the data folder of the current directory, you can also change it to an absolute path like -v /your/custom/path:/data

---

🎉 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

📖 Official Documentation |

Quick Navigation:

Category	Link
🚀 Deployment Guide	Installation Documentation
⚙️ Environment Configuration	Environment Variables
📡 API Documentation	API Documentation
❓ FAQ	FAQ
💬 Community Interaction	Communication Channels

---

✨ Key Features

For detailed features, please refer to Features Introduction

🎨 Core Functions

Feature	Description
🎨 New UI	Modern user interface design
🌍 Multi-language	Supports Simplified Chinese, Traditional Chinese, English, French, Japanese
🔄 Data Compatibility	Fully compatible with the original One API database
📈 Data Dashboard	Visual console and statistical analysis
🔒 Permission Management	Token grouping, model restrictions, user management

💰 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:

View detailed configuration

OpenAI series models:

• o3-mini-high - High reasoning effort
• o3-mini-medium - Medium reasoning effort
• o3-mini-low - Low reasoning effort
• gpt-5-high - High reasoning effort
• gpt-5-medium - Medium reasoning effort
• gpt-5-low - Low reasoning effort

Claude thinking models:

• claude-3-7-sonnet-20250219-thinking - Enable thinking mode

Google Gemini series models:

• gemini-2.5-flash-thinking - Enable thinking mode
• gemini-2.5-flash-nothinking - Disable thinking mode
• gemini-2.5-pro-thinking - Enable thinking mode
• gemini-2.5-pro-thinking-128 - Enable thinking mode with thinking budget of 128 tokens
• You can also append -low, -medium, or -high to any Gemini model name to request the corresponding reasoning effort (no extra thinking-budget suffix needed).

---

🤖 Model Support

For details, please refer to API Documentation - Gateway Interface

Model Type	Description	Documentation
🤖 OpenAI-Compatible	OpenAI compatible models	Documentation
🤖 OpenAI Responses	OpenAI Responses format	Documentation
🎨 Midjourney-Proxy	Midjourney-Proxy(Plus)	Documentation
🎵 Suno-API	Suno API	Documentation
🔄 Rerank	Cohere, Jina	Documentation
💬 Claude	Messages format	Documentation
🌐 Gemini	Google Gemini format	Documentation
🔧 Dify	ChatFlow mode	-
🎯 Custom upstream	Supports configuring legally authorized upstream endpoints	-

📡 Supported Interfaces

View complete interface list

• Chat Interface (Chat Completions)
• Response Interface (Responses)
• Image Interface (Image)
• Audio Interface (Audio)
• Video Interface (Video)
• Embedding Interface (Embeddings)
• Rerank Interface (Rerank)
• Realtime Conversation (Realtime)
• Claude Chat
• Google Gemini Chat

---

🚢 Deployment

Tip

Latest Docker image: calciumion/new-api:latest

📋 Deployment Requirements

Component	Requirement
Local database	SQLite (Docker must mount /data directory)
Remote database	MySQL ≥ 5.7.8 or PostgreSQL ≥ 9.6
Container engine	Docker / Docker Compose
System architecture	64-bit only (amd64 / arm64); 32-bit systems are not supported

⚙️ Environment Variable Configuration

Common environment variable configuration

Variable Name	Description	Default Value
SESSION_SECRET	Authentication signing secret; must be identical on every node	-
SESSION_COOKIE_SECURE	false/unset disables the refresh/logout OriginGuard for local HTTP dev proxies; true enables the Secure cookie and strict Origin checks	false
SESSION_COOKIE_TRUSTED_URL	Required with Secure mode: comma-separated exact HTTPS Origins allowed to call refresh/logout; not a relay CORS allowlist	-
TRUSTED_PROXIES	Unset/blank trusts loopback, RFC 1918 and IPv6 ULA with a startup warning; none trusts no proxies; an explicit proxy IP/CIDR list replaces the defaults	127.0.0.0/8, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7
USER_SESSION_ACTIVE_LIMIT	Maximum active login Sessions per user	50
USER_SESSION_ISSUANCE_LIMIT	Maximum Sessions created per user within the issuance window, including revoked Sessions	100
USER_SESSION_ISSUANCE_WINDOW_SECONDS	Per-user Session issuance window; clamped to the revoked retention period when configured higher	86400
USER_SESSION_REVOKED_RETENTION_DAYS	Days to retain revoked Session rows for audit and issuance accounting	7
USER_SESSION_HOURLY_ALERT_THRESHOLD	Global Sessions created per hour that triggers an alert only; it never blocks login	5000
CRYPTO_SECRET	HMAC secret for cache keys; nodes sharing Redis must use the same effective value	Defaults to SESSION_SECRET
SQL_DSN	Database connection string	-
REDIS_CONN_STRING	Redis connection string	-
RELAY_IDLE_CONN_TIMEOUT	Idle keep-alive timeout for relay HTTP clients, seconds. Defaults to Go standard library behavior; set 0 to disable	90
RELAY_RESPONSE_HEADER_TIMEOUT	How long the relay waits for upstream response headers, seconds; set 0 to disable. Only bounds the header wait -- streaming after the headers arrive is unaffected. Note that non-streaming upstreams usually send headers only once generation finishes, so leave headroom	1800
STREAMING_TIMEOUT	Streaming timeout (seconds)	300
STREAM_SCANNER_MAX_BUFFER_MB	Max per-line buffer (MB) for the stream scanner; increase when upstream sends huge image/base64 payloads	64
MAX_REQUEST_BODY_MB	Max request body size (MB, counted after decompression; prevents huge requests/zip bombs from exhausting memory). Exceeding it returns 413	32
AZURE_DEFAULT_API_VERSION	Azure API version	2025-04-01-preview
ERROR_LOG_ENABLED	Error log switch	false
PYROSCOPE_URL	Pyroscope server address	-
PYROSCOPE_APP_NAME	Pyroscope application name	new-api
PYROSCOPE_BASIC_AUTH_USER	Pyroscope basic auth user	-
PYROSCOPE_BASIC_AUTH_PASSWORD	Pyroscope basic auth password	-
PYROSCOPE_MUTEX_RATE	Pyroscope mutex sampling rate	5
PYROSCOPE_BLOCK_RATE	Pyroscope block sampling rate	5
HOSTNAME	Hostname tag for Pyroscope	new-api

📖 Complete configuration: Environment Variables Documentation

🔧 Deployment Methods

Method 1: Docker Compose (Recommended)

# 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

Method 2: Docker Commands

Using SQLite:

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

💡 Path explanation:

• ./data:/data - Relative path, data saved in the data folder of the current directory
• You can also use absolute path, e.g.: /your/custom/path:/data

Method 3: BaoTa Panel

1. Install BaoTa Panel (≥ 9.2.0 version)
2. Search for New-API in the application store
3. One-click installation

📖 Tutorial with images

⚠️ 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.

Redis topology	Session propagation	Rate limiting
Shared Redis	Revocations and version publications normally propagate immediately	Redis limits are shared across nodes
Independent Redis per node	Nodes converge from the database within the effective SYNC_FREQUENCY; a newly rotated token may receive a temporary 401 on a node with stale cache	Each node has its own allowance, so aggregate capacity can reach roughly the configured limit multiplied by the node count
No Redis	Every Session validation reads the database	In-memory limits are independent per node

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

Project	Description
One API	Original project base
Midjourney-Proxy	Midjourney interface support

Supporting Tools

Project	Description
new-api-key-tool	Key quota query tool
new-api-horizon	New API high-performance optimized version

---

💬 Help Support

📖 Documentation Resources

Resource	Link
📘 FAQ	FAQ
💬 Community Interaction	Communication Channels
🐛 Issue Feedback	Issue Feedback
📚 Complete Documentation	Official Documentation

🤝 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: support@quantumnous.com

---

🌟 Star History

---

💖 Thank you for using New API

If this project is helpful to you, welcome to give us a ⭐️ Star！

Official Documentation • Issue Feedback • Latest Release

_{Built with ❤️ by QuantumNous}