## ๐ 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.
---
## ๐ ๏ธ Backend Implementations
This project provides **two functionally equivalent backend implementations** so you can choose the technology stack that best fits your team and infrastructure. Both versions expose the same HTTP APIs, share the same database schema, and are wire-compatible with the same frontend and clients.
| Version | Language / Framework | Location | Recommended Use Case |
|---------|----------------------|----------|----------------------|
| ๐น **Go Version** | Go + Gin + GORM | Repository root (`main.go`, `controller/`, `relay/`, `model/`, ...) | High concurrency, low memory footprint, single-binary deployment, container-first environments |
| โ **Java Version** | Java 17 + Spring Boot + MyBatis / JPA | `new-api-java/` (planned / in progress) | Enterprises standardized on the JVM ecosystem, integration with existing Spring / microservice infrastructure, easier customization for Java teams |
### Feature Parity
Both backend implementations aim to provide:
- โ
Identical REST / streaming APIs (OpenAI-compatible, Claude Messages, Gemini, Rerank, etc.)
- โ
Identical database models (MySQL / PostgreSQL / SQLite) and Redis cache keys
- โ
Identical authentication, session, quota, billing, and channel-routing behavior
- โ
Shared frontend (`web/`) โ the same UI works against either backend
### Choosing a Version
- Pick the **Go version** if you want the smallest resource footprint, fastest cold start, and the reference implementation with the most up-to-date features.
- Pick the **Java version** if your organization mandates the JVM stack, or you need to integrate with existing Spring Boot / Spring Cloud services, JVM-based observability, or enterprise middleware.
> [!NOTE]
> The Go version is the reference implementation. New features generally land in the Go version first and are ported to the Java version afterward.
---
## ๐ค 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)
```bash
# 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
```bash
# 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](https://docs.newapi.pro/en/docs/installation)
---
## ๐ Documentation
### ๐ [Official Documentation](https://docs.newapi.pro/en/docs) | [](https://deepwiki.com/QuantumNous/new-api)
**Quick Navigation:**
| Category | Link |
|------|------|
| ๐ Deployment Guide | [Installation Documentation](https://docs.newapi.pro/en/docs/installation) |
| โ๏ธ Environment Configuration | [Environment Variables](https://docs.newapi.pro/en/docs/installation/config-maintenance/environment-variables) |
| ๐ก API Documentation | [API Documentation](https://docs.newapi.pro/en/docs/api) |
| โ FAQ | [FAQ](https://docs.newapi.pro/en/docs/support/faq) |
| ๐ฌ Community Interaction | [Communication Channels](https://docs.newapi.pro/en/docs/support/community-interaction) |
---
## โจ Key Features
> For detailed features, please refer to [Features Introduction](https://docs.newapi.pro/en/docs/guide/wiki/basic-concepts/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](https://github.com/Calcium-Ion/new-api-key-tool))
### ๐ Advanced Features
**API Format Support:**
- โก [OpenAI Responses](https://docs.newapi.pro/en/docs/api/ai-model/chat/openai/create-response)
- โก [OpenAI Realtime API](https://docs.newapi.pro/en/docs/api/ai-model/realtime/create-realtime-session) (including Azure)
- โก [Claude Messages](https://docs.newapi.pro/en/docs/api/ai-model/chat/create-message)
- โก [Google Gemini](https://doc.newapi.pro/en/api/google-gemini-chat)
- ๐ [Rerank Models](https://docs.newapi.pro/en/docs/api/ai-model/rerank/create-rerank) (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](https://docs.newapi.pro/en/docs/api)
| Model Type | Description | Documentation |
|---------|------|------|
| ๐ค OpenAI-Compatible | OpenAI compatible models | [Documentation](https://docs.newapi.pro/en/docs/api/ai-model/chat/openai/createchatcompletion) |
| ๐ค OpenAI Responses | OpenAI Responses format | [Documentation](https://docs.newapi.pro/en/docs/api/ai-model/chat/openai/createresponse) |
| ๐จ Midjourney-Proxy | [Midjourney-Proxy(Plus)](https://github.com/novicezk/midjourney-proxy) | [Documentation](https://doc.newapi.pro/api/midjourney-proxy-image) |
| ๐ต Suno-API | [Suno API](https://github.com/Suno-API/Suno-API) | [Documentation](https://doc.newapi.pro/api/suno-music) |
| ๐ Rerank | Cohere, Jina | [Documentation](https://docs.newapi.pro/en/docs/api/ai-model/rerank/creatererank) |
| ๐ฌ Claude | Messages format | [Documentation](https://docs.newapi.pro/en/docs/api/ai-model/chat/createmessage) |
| ๐ Gemini | Google Gemini format | [Documentation](https://docs.newapi.pro/en/docs/api/ai-model/chat/gemini/geminirelayv1beta) |
| ๐ง Dify | ChatFlow mode | - |
| ๐ฏ Custom upstream | Supports configuring legally authorized upstream endpoints | - |
### ๐ก Supported Interfaces
View complete interface list
- [Chat Interface (Chat Completions)](https://docs.newapi.pro/en/docs/api/ai-model/chat/openai/createchatcompletion)
- [Response Interface (Responses)](https://docs.newapi.pro/en/docs/api/ai-model/chat/openai/createresponse)
- [Image Interface (Image)](https://docs.newapi.pro/en/docs/api/ai-model/images/openai/post-v1-images-generations)
- [Audio Interface (Audio)](https://docs.newapi.pro/en/docs/api/ai-model/audio/openai/create-transcription)
- [Video Interface (Video)](https://docs.newapi.pro/en/docs/api/ai-model/audio/openai/createspeech)
- [Embedding Interface (Embeddings)](https://docs.newapi.pro/en/docs/api/ai-model/embeddings/createembedding)
- [Rerank Interface (Rerank)](https://docs.newapi.pro/en/docs/api/ai-model/rerank/creatererank)
- [Realtime Conversation (Realtime)](https://docs.newapi.pro/en/docs/api/ai-model/realtime/createrealtimesession)
- [Claude Chat](https://docs.newapi.pro/en/docs/api/ai-model/chat/createmessage)
- [Google Gemini Chat](https://docs.newapi.pro/en/docs/api/ai-model/chat/gemini/geminirelayv1beta)
---
## ๐ข 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` |
| `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](https://docs.newapi.pro/en/docs/installation/config-maintenance/environment-variables)
### ๐ง Deployment Methods
Method 1: Docker Compose (Recommended)
```bash
# 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:**
```bash
docker run --name new-api -d --restart always \
-p 3000:3000 \
-e TZ=Asia/Shanghai \
-v ./data:/data \
calciumion/new-api:latest
```
**Using MySQL:**
```bash
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](./docs/BT.md)
### โ ๏ธ 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](./docs/authentication.md) 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](https://github.com/songquanpeng/one-api) | Original project base |
| [Midjourney-Proxy](https://github.com/novicezk/midjourney-proxy) | Midjourney interface support |
### Supporting Tools
| Project | Description |
|------|------|
| [new-api-key-tool](https://github.com/Calcium-Ion/new-api-key-tool) | Key quota query tool |
| [new-api-horizon](https://github.com/Calcium-Ion/new-api-horizon) | New API high-performance optimized version |
---
## ๐ฌ Help Support
### ๐ Documentation Resources
| Resource | Link |
|------|------|
| ๐ FAQ | [FAQ](https://docs.newapi.pro/en/docs/support/faq) |
| ๐ฌ Community Interaction | [Communication Channels](https://docs.newapi.pro/en/docs/support/community-interaction) |
| ๐ Issue Feedback | [Issue Feedback](https://docs.newapi.pro/en/docs/support/feedback-issues) |
| ๐ Complete Documentation | [Official Documentation](https://docs.newapi.pro/en/docs) |
### ๐ค 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)](./LICENSE).
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: .
This is an open-source project developed based on [One API](https://github.com/songquanpeng/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](mailto:support@quantumnous.com)
---
## ๐ Star History
[](https://star-history.com/#Calcium-Ion/new-api&Date)
---
### ๐ Thank you for using New API
If this project is helpful to you, welcome to give us a โญ๏ธ Star๏ผ
**[Official Documentation](https://docs.newapi.pro/en/docs)** โข **[Issue Feedback](https://github.com/Calcium-Ion/new-api/issues)** โข **[Latest Release](https://github.com/Calcium-Ion/new-api/releases)**
Built with โค๏ธ by QuantumNous
