- payment_setting.amount_bonus: uniform top-up bonus (1 = pay ¥1 credit ¥2), applied to credited quota in model/topupQuotaFromAmount and controller/getTopUpQuota (epay/waffo/pancake/manual paths), exposed via /api/user/topup/info; regression test TestTopUpQuotaAppliesAmountBonus - wallet recharge card: bonus banner, credited amount per preset, custom-amount credited line, credited row in payment confirm dialog; hardcoded Chinese copy (支付/到账/最低充值) - list locale defaults: Chinese-first, browser locale no longer auto-selects English; new localStorage key resets stale language caches - /docs top-up section: bonus notice box - README: record the recharge-bonus update in 'About This Custom Fork'
26 KiB
New API
🍥 Next-Generation LLM Gateway and AI Asset Management System
简体中文 | 繁體中文 | English | Français | 日本語
Quick Start • Key Features • Deployment • Documentation • Help
🌟 About This Custom Fork
This repository is a customized fork of upstream QuantumNous/new-api (based on
v1.0.0-rc.36). Live demo: https://ai.88531.cn (sign-up bonus ¥0.1, plus ¥0.5 daily check-in reward)
Changes vs upstream
| Feature | Description |
|---|---|
| 💰 Native CNY billing | Quota is displayed in CNY: top-up amount equals RMB paid, credited quota = amount ÷ Price × QuotaPerUnit. No exchange-rate conversion in the wallet; applies to all top-up channels such as Epay and Waffo (controller/topup.go, model/topup.go) |
| 🎉 Recharge bonus (pay 1 get 2) | New uniform top-up bonus: set payment_setting.amount_bonus to 1.0 and every ¥1 paid credits ¥2 of quota ("充多少送多少"). Backend multiplies credited quota in model/topupQuotaFromAmount (covers Epay/Waffo/pancake/补单 paths) and controller/getTopUpQuota keeps validation consistent; bonus ratio is exposed via /api/user/topup/info. The wallet recharge card shows a 100%-bonus banner, per-preset credited amounts ("到账 ¥2"), custom-amount credited line, and a credited amount row in the payment confirm dialog — all hardcoded Chinese for the zh audience |
| 🈷️ Chinese-first i18n | Recharge UI texts are written directly in Chinese (banner, "支付"/"到账", placeholders). Site language no longer follows the browser locale: it defaults to Chinese (fallback zhCN) and honors a user's manual switch only; old language caches are reset via a new storage key |
| 🎁 Daily check-in + header button | New CheckinButton component in both authenticated and public headers, with Turnstile support; guides anonymous visitors to sign up |
📦 Subscription plans page /subscribe |
Public plan listing (reads a plans.json snapshot when logged out, system API when logged in), supports Alipay purchase, balance payment, and free claims; auto group upgrade on purchase, periodic quota reset, auto downgrade on expiry |
📖 Built-in usage docs /docs |
A brand-new 12-section beginner guide (intro, quick start, check-in, top-up, group explanation, API keys, pricing, Playground, third-party clients, API examples, FAQ) with sticky anchor navigation |
| 📣 Home promo banner | Neon gradient PromoBanner on the home page linking to the docs page |
| 🌍 i18n | New check-in strings synced across en / zh / zh-TW / fr / ja / ru / vi |
Tip
Try it live at https://ai.88531.cn: get ¥0.1 on sign-up and ¥0.5 per daily check-in — no deposit needed to try 30+ models including GLM, DeepSeek, and Kimi.
🗒️ 更新日志(Latest update — 充值优惠上线)
2026-09-24 · v"充值优惠"(RC42)
- 充值优惠「充 1 元到账 2 元」
- 后端新增统一赠送比例
payment_setting.amount_bonus:1= 充多少送多少(¥1 实到 ¥2),0= 关闭;改数据库一行再重启即可调整,无需改代码 - 到账额度统一在
topupQuotaFromAmount/getTopUpQuota乘以(1 + bonus),覆盖易支付、Waffo、Pancake、管理员补单全部到账路径;Stripe/Creem 保持原有逻辑 - 携带回归测试
TestTopUpQuotaAppliesAmountBonus(含赠送关闭恢复原状)
- 后端新增统一赠送比例
- 充值页展示优惠(位置:控制台 → 钱包)
- 顶部绿色横幅:「充值优惠:充值 1 元实际到账 2 元,以此类推,充多少送多少。」
- 每个金额档显示「到账 ¥x」(绿色)+「支付 ¥x · 已省 ¥x」
- 自定义金额旁显示「待支付金额」+「到账金额」两行;输入框占位符改「最低充值 N」
- 支付确认弹窗新增「到账金额」绿色行
- 文档页
/docs第 05 节「充值与包月套餐」加入优惠说明框(¥10→¥20、¥100→¥200 举例) - 关于页(后台可编辑的 HTML 内容)新增「🎁 充值优惠 · 充 1 元到账 2 元」小节,含 ¥1/¥10/¥100 到账价格卡片
- 默认中文:i18n 不再跟随浏览器语言,默认中文;充值页关键文案直接中文写死,避免英文浏览器显示英文
配置入口:数据库
options表payment_setting.amount_bonus(如改回0即取消优惠)。关于页优惠小节保存在options表的About键中,可在后台 系统设置 → 导航 内容里继续编辑。
📝 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:/datawill save data in thedatafolder 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:
| 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 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-highto 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
🚢 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
⚠️ 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
