new-api is a unified AI model gateway for aggregating and distributing LLMs, cross-converting providers into OpenAI, Claude, or Gemini compatible APIs. After 21 days running it as the model router for saas.pet's backend, here is the real story on channel management, token billing, and the AGPL license tradeoff.
What new-api actually is
new-api is a self-hosted AI model gateway written in Go. It aggregates model providers, DeepSeek, GLM, Qwen, OpenAI, Claude, Gemini, MiniMax, whatever has an API, and re-exposes them through OpenAI-compatible, Claude-compatible, and Gemini-compatible endpoints. Your application code never talks to providers directly. It talks to new-api, and new-api routes to the right upstream based on channel priority, model availability, and fallback rules. The project is maintained by QuantumNous, the team behind the Qwen open-weight models, and it is the de facto successor to one-api, which stopped active development. As of August 2026 it has 45,733 stars, an AGPL-3.0 license, and the latest release is v1.0.0-rc.25 from 2026-08-18. It is still shipping release candidates, which tells you the API surface is stabilizing but not frozen. The feature set includes channel management, per-channel rate limiting, token-based billing with a user system, usage logging with cost accounting, model list filtering per channel, and a web dashboard in Chinese and English.
Why I run it: one base URL for everything
saas.pet's backend calls multiple models for different jobs: MiniMax for the search API, DeepSeek for content generation, and a couple of others for specific features. Before new-api, every service had its own provider SDK, its own API key, and its own error handling, and when a provider had an outage I edited environment variables and redeployed. With new-api, every service points at one base URL with one key. The routing layer decides which upstream actually serves the request. Adding a provider is a dashboard form, not a code change. The moment that clicked for me was a MiniMax API hiccup last week: the search endpoint kept returning 5xx, and because I had configured DeepSeek as a fallback channel for the same model alias, new-api failed over automatically. I noticed in the usage log after the fact instead of getting paged. That single incident justified the migration.
Channel management and model aliasing
The core workflow in new-api is channels and model aliases. A channel is one upstream provider with one or more API keys. A model alias maps a logical model name, like gpt-4o or deepseek-chat, to one or more channels. When a request comes in for a model name, new-api picks a channel by priority, tests it if configured, and falls back to the next channel on failure. This is where the aggregation value lives. I run DeepSeek with two channels, primary and backup keys, and MiniMax with one. The dashboard shows per-channel latency, error rates, and token usage, which is the visibility you never get when providers are called directly from app code. The model list feature lets you hide upstream models you do not want exposed, which matters if you are offering the gateway to other people. The rate limiting is per-channel and per-token, and I have it set so a runaway loop in a test script cannot burn a month of quota in an hour.
Token billing and the user system
new-api ships a full token and user system: create users, issue API tokens, set quotas and expiration, and track spend per token per model. This is the distribution half of aggregation and distribution, and it is the reason new-api, not LiteLLM, is the popular choice in the Chinese developer ecosystem. Many deployments use it to resell API access internally or to teams, with quota enforcement. I use a lighter version: a separate token per service, search gets its own quota, content generation gets its own, and the dashboard shows monthly spend per service at a glance. The accounting is in tokens and dollars, and the conversion rates are configurable per model. The user system is more than I need as a solo operator, but the per-token quotas and logs are exactly right for keeping model costs under control. If you have ever gotten a surprise provider bill, this alone justifies the setup.
Comparing with one-api, LiteLLM, and cloud gateways
Against one-api, its predecessor, new-api is strictly better: same architecture, active maintenance, more providers, better dashboard, and the community has migrated. The only reason to stay on one-api is if you have a deeply customized fork. Against LiteLLM, the comparison is about audience. LiteLLM is a Python library and proxy aimed at developers who want fine-grained control and a huge provider catalog; it is excellent but configuration is code, and it has no billing or user system out of the box. new-api is an application with a web dashboard, quotas, and users. If you are a developer who lives in config files, LiteLLM feels natural. If you want a self-contained gateway with accounting, new-api wins. Against Vercel AI Gateway, the cloud option, new-api wins on data control and cost, it is free to self-host, and loses on zero maintenance. For a solo project on a VPS, self-hosted new-api is the right call.
Deployment and maintenance cost
new-api is a single Go binary plus a database. I run it with SQLite on the same VPS as my other services, no Docker even though Docker images are provided. The binary is about 60MB, memory usage sits around 150MB, and startup is instant. Upgrading is download the new binary, restart the service, done, and the dashboard shows the current version with a one-click check for updates. The database migration on version upgrades has been smooth in my three weeks, including the RC version jumps. The main operational cost is watching the GitHub releases page for RC updates, since the project is pre-1.0. I pin versions and read the changelog before upgrading. Total maintenance time: under an hour a month. The web dashboard is where you spend your time: checking channel health, reviewing usage, and occasionally re-adding a provider key when one rotates.
The AGPL-3.0 license is the real constraint
new-api is AGPL-3.0, and that is a decision you need to make before adopting it, not after. AGPL is the strong copyleft license: if you modify the code and run it as a network service, you must release your modifications under AGPL. For saas.pet, running new-api unmodified as a separate service does not infect my codebase, the gateway is a standalone component talking to my backend over HTTP. That is the standard interpretation and it is fine for my use case. What is not fine: embedding new-api's code inside a closed-source commercial product, or building a proprietary resale platform on a modified fork. If either of those is your plan, look at the MIT-licensed alternatives or the commercial route. The practical advice: keep new-api as a separate process, do not fork it, and the license is a non-issue. I also check the license file on every upgrade because project licenses have been known to change.
Limitations and final verdict
The honest limitations: pre-1.0 release candidates mean occasional breaking changes, the documentation assumes you know the one-api lineage, the UI is Chinese-first with English as a translation, and advanced routing policies, like cost-aware routing or latency-based load balancing, are not as rich as what a cloud gateway offers. The model catalog depends on community-contributed providers, so an obscure provider may need a manual channel config. Who should skip new-api: if you call exactly one model from one provider, a gateway is pure overhead. If you need enterprise-grade routing and are okay with vendor lock-in, use a cloud gateway. For anyone running two or more models in production, the aggregation, failover, and billing visibility pay for the setup within the first outage or the first surprise bill. I give it 4 out of 5, and the missing point is the pre-1.0 roughess. When it ships 1.0 stable, this is a 5.
Pros
- One OpenAI-compatible endpoint for every provider, zero provider SDKs in app code
- Automatic channel failover, verified in a real MiniMax outage
- Per-token quotas, usage logs, and cost accounting in the dashboard
- Single Go binary, ~150MB RAM, upgrades are a binary swap
- Active maintenance: releases weekly, 45k stars
- Supports OpenAI, Claude, and Gemini compatible response formats
Cons
- AGPL-3.0 copyleft: no embedding in closed-source commercial products
- Pre-1.0 release candidates, breaking changes possible
- UI is Chinese-first, English translation is incomplete
- Advanced routing policies thinner than cloud gateways
- Documentation assumes knowledge of the one-api lineage
- Overkill if you use a single model from a single provider
This review originally appeared on saas.pet — I test AI tools with my own money and write about what actually works.
Top comments (0)