📝 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
Quick Navigation:
✨ 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:
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 efforto3-mini-medium - Medium reasoning efforto3-mini-low - Low reasoning effortgpt-5-high - High reasoning effortgpt-5-medium - Medium reasoning effortgpt-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 modegemini-2.5-flash-nothinking - Disable thinking modegemini-2.5-pro-thinking - Enable thinking modegemini-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
📡 Supported Interfaces
View complete interface list
🚢 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
- Install BaoTa Panel (≥ 9.2.0 version)
- Search for New-API in the application store
- 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
Upstream Projects
💬 Help Support
📖 Documentation Resources
New API 是一个可自行部署的网关，通过单一端点统一访问多家 AI 服务商（如 OpenAI、Claude、Gemini、DeepSeek 等），并在 OpenAI、Claude 和 Gemini 兼容格式之间进行转换，同时提供用量统计、计费和访问控制功能。