![new-api](/web/public/logo.png) # New API 🍥 **Next-Generation LLM Gateway and AI Asset Management System**

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

license release docker AtomGit G-Star

QuantumNous%2Fnew-api | Trendshift
Featured|HelloGitHub AtomGit G-Star

Quick Start • Key Features • Deployment • Documentation • Help

--- ## 🌟 About This Custom Fork > This repository is a customized fork of upstream [QuantumNous/new-api](https://github.com/QuantumNous/new-api) (based on `v1.0.0-rc.36`). > **Live demo: ** (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 : 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. **充值优惠「充 1 元到账 2 元」** - 后端新增统一赠送比例 `payment_setting.amount_bonus`:`1` = 充多少送多少(¥1 实到 ¥2),`0` = 关闭;改数据库一行再重启即可调整,无需改代码 - 到账额度统一在 `topupQuotaFromAmount` / `getTopUpQuota` 乘以 `(1 + bonus)`,覆盖易支付、Waffo、Pancake、管理员补单全部到账路径;Stripe/Creem 保持原有逻辑 - 携带回归测试 `TestTopUpQuotaAppliesAmountBonus`(含赠送关闭恢复原状) 2. **充值页展示优惠**(位置:控制台 → 钱包) - 顶部绿色横幅:「充值优惠:充值 1 元实际到账 2 元,以此类推,充多少送多少。」 - 每个金额档显示「到账 ¥x」(绿色)+「支付 ¥x · 已省 ¥x」 - 自定义金额旁显示「待支付金额」+「到账金额」两行;输入框占位符改「最低充值 N」 - 支付确认弹窗新增「到账金额」绿色行 3. **文档页 `/docs`** 第 05 节「充值与包月套餐」加入优惠说明框(¥10→¥20、¥100→¥200 举例) 4. **关于页**(后台可编辑的 HTML 内容)新增「🎁 充值优惠 · 充 1 元到账 2 元」小节,含 ¥1/¥10/¥100 到账价格卡片 5. **默认中文**: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

Cherry Studio Aion UI Peking University UCloud Alibaba Cloud IO.NET

--- ## 🙏 Special Thanks

JetBrains Logo

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) | [![Ask DeepWiki](https://deepwiki.com/badge.svg)](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/videos/sora/createvideo) - [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` | | `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](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
[![Star History Chart](https://api.star-history.com/svg?repos=Calcium-Ion/new-api&type=Date)](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