New API

🍥 Next-Generation Large Model Gateway and AI Asset Management System

中文 | English | Français | 日本語

Quick Start • Key Features • Deployment • Documentation • Help

📝 Project Description

Note

This is an open-source project developed based on One API

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

🚀 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 GPTs	gpt-4-gizmo-* series	-
🎨 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

🚢 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	-
`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

🔗 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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New API

📝 Project Description

🤝 Trusted Partners

🙏 Special Thanks

🚀 Quick Start

Using Docker Compose (Recommended)

📚 Documentation

📖 Official Documentation |

✨ Key Features

🎨 Core Functions

💰 Authorized Usage Accounting and Billing

🔐 Authorization and Security

🚀 Advanced Features

🤖 Model Support

📡 Supported Interfaces

🚢 Deployment

📋 Deployment Requirements

⚙️ Environment Variable Configuration

🔧 Deployment Methods

⚠️ Multi-machine Deployment Considerations

🔄 Channel Retry and Cache

🔗 Related Projects

Upstream Projects

Supporting Tools

💬 Help Support

📖 Documentation Resources

🤝 Contribution Guide

🌟 Star History

💖 Thank you for using New API

FilesExpand file tree

README.en.md

Latest commit

History

README.en.md

File metadata and controls

New API

📝 Project Description

🤝 Trusted Partners

🙏 Special Thanks

🚀 Quick Start

Using Docker Compose (Recommended)

📚 Documentation

📖 Official Documentation |

✨ Key Features

🎨 Core Functions

💰 Authorized Usage Accounting and Billing

🔐 Authorization and Security

🚀 Advanced Features

🤖 Model Support

📡 Supported Interfaces

🚢 Deployment

📋 Deployment Requirements

⚙️ Environment Variable Configuration

🔧 Deployment Methods

⚠️ Multi-machine Deployment Considerations

🔄 Channel Retry and Cache

🔗 Related Projects

Upstream Projects

Supporting Tools

💬 Help Support

📖 Documentation Resources

🤝 Contribution Guide

🌟 Star History

💖 Thank you for using New API