One API

Last reviewed Aug 26, 2026 · 783 words

One API gives every tool in your homelab a single https://llm.example.com/v1 endpoint and a single key, then routes each request to Ollama, OpenAI, Anthropic, Gemini or a dozen other providers behind it, with per-user quotas and a usage ledger. Before any of that, change the admin password: the default login is root with password 123456 and the project does not force a change on first boot. That one fact, plus documentation that is mostly in Chinese, is the whole cost of a tool that otherwise does one job unusually well. 36,581 stars, MIT, and it idles in about 256 MB.

The problem it solves in one sentence

Ten self-hosted apps each want an OpenAI API key and base URL. Without a gateway you paste ten copies of the same key, cannot tell which app spent what, and cannot swap a model without editing ten configs. With One API each app gets its own token, each token carries a quota, and the model name in the request maps to whichever channel you point it at. Swap a channel from a paid model to a local one and every app follows, none of them knowing.

Channels, tokens, quotas

A channel is an upstream: type (OpenAI, Anthropic, Ollama through its OpenAI-compatible endpoint, Azure, and so on), base URL, key, and the list of models it serves. A token is a downstream credential you hand to an app, scoped to models and a quota. Quotas are counted in a currency-like unit converted from tokens per model, and you set the exchange rates. When several channels serve the same model, requests go to a random pick among the highest-priority ones, so two Ollama hosts, or a local model with a paid fallback, is two channels and one priority difference. That is the pattern that makes Ollama usable for a household: local first, paid only when the local box is down.

Running it

services:
  one-api:
    image: justsong/one-api:latest
    ports:
      - "3000:3000"
    environment:
      TZ: Europe/Dublin
    volumes:
      - ./data:/data
    restart: unless-stopped

SQLite in /data is fine for a household. The moment you have more than a handful of users or multiple replicas, set SQL_DSN to a MySQL or Postgres URL, because SQLite is the path the project itself warns about for scale. Log in, change the root password, create a channel for each provider, then a token per app. Point Open WebUI at http://one-api:3000/v1 with that token and you have a chat front-end whose spend you can read off a dashboard. The Logs tab records every request with model, token counts and which channel served it, which is also the fastest way to debug an app that swears it sent the right model name. Redemption codes let you top up a user's quota without touching the database, a small feature that matters once someone other than you is on it.

The Chinese documentation is a real constraint

The README has an English section and the UI is translated, but the depth, the FAQ and the issue tracker are in Chinese. Browser translation gets you most of the way; the settings you need are in the UI's Settings tab and named sensibly. If that is a dealbreaker, New API is the actively maintained fork with more providers and the same model, and LiteLLM is the Python alternative with English docs and a YAML config instead of a UI.

One API vs LiteLLM

LiteLLM is the gateway developers reach for: config in a file, a proxy with the same channel-and-key idea, and deep integration with observability tools. One API is the gateway for operators who want a web UI, user accounts and a billing view without writing YAML. They overlap almost entirely on the core job. Pick LiteLLM if the people using it are you and your code; pick One API if you are handing tokens to family members or colleagues and want to see who used what. The LLM runners category covers the model servers that sit behind either.

What I'd do

The compose file above, root password changed within the first minute, Ollama as channel one with high priority, a paid provider as channel two with low priority for the same model names. One token per app, each with a monthly quota. Put it behind HTTPS and keep the admin UI off the public internet. For a home with 3 people and 6 apps this is the difference between an AI budget you can see and one you discover on a credit card statement.