Skip to content
Get packs

Guide · Open source

How to use One API: install with Docker and manage LLM keys

Updated · written with AI from the project's own documentation and checked against our catalogue data

One API is a self-hosted web service that sits between your applications and many large language model providers, including OpenAI, Azure, Claude, Gemini and DeepSeek. Your apps send requests in the standard OpenAI API format, and One API passes them to the provider you have configured. This guide shows you how to start it with Docker, sign in, and get to a working setup.

One APIsongquanpeng/one-api · ★ 37.3k · MIT

Quick start

  1. 1Install Docker. Make sure Docker is installed and running on the server where One API will run.
  2. 2Create a data directory. Create the host directory you want to use for data and logs, such as /home/ubuntu/data/one-api, and make sure it is writable.
  3. 3Start the container. Run the README's docker run command with SQLite, which maps port 3000 and mounts your data directory.
  4. 4Sign in as root. Open http://localhost:3000/ and log in with username root and the initial password 123456.
  5. 5Change the default password. Immediately change the root password from 123456 in the admin panel.
  6. 6Add channels. Configure one or more provider channels and their model lists in the admin panel.
  7. 7Issue tokens. Create tokens with expiry times, quotas, IP ranges and model access rules for your apps or members.

What One API does and who it is for

One API unifies several providers under a single API, so clients can use one OpenAI-compatible endpoint. It also includes a web admin panel for issuing tokens, setting quotas and managing channels.

It suits developers who want one endpoint for several providers, small teams that need to issue and limit keys to members, and operators who want load balancing or retries across channels. If you only call one provider, it adds a service to run that you may not need.

  • Requirement: Docker
  • The project is MIT licensed and has an English UI
  • Software you deploy and maintain yourself, not a hosted service

Start One API with Docker

The README's command below runs One API with SQLite. It maps port 3000 on your host to the container and stores data in the host directory you specify. Make sure that directory exists and is writable before you start.

Replace the host path with one that suits your server if needed. The first number in -p 3000:3000 is the host port and can be changed.

  • If the container fails to start, the README suggests adding --privileged=true.
  • If justsong/one-api cannot be pulled, you can use ghcr.io/songquanpeng/one-api instead.
  • For higher concurrency, the README says to set SQL_DSN to use a database such as MySQL.
docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

Sign in and change the default password

Open http://localhost:3000/ in your browser and sign in. The initial account is username root with password 123456.

The README warns you to change this default password as soon as you first log in as root.

  • Username: root
  • Initial password: 123456 (change it immediately)

Add provider channels

Channels connect One API to the upstream model providers. The README lists supported providers including OpenAI (with Azure OpenAI API), Anthropic Claude, Google Gemini, Mistral, DeepSeek, Ollama, Groq and many others.

The admin panel supports channel management and batch creation of channels. You can also set a model list for each channel, and set a proxy or mirror address where the source describes it.

  • Each provider is a channel you configure in the admin panel
  • You can set a model list per channel
  • Failed requests can be retried automatically

Issue tokens and set limits for members

Tokens are the API keys your apps and users send to One API. In token management you can set an expiry time, a quota, the allowed IP ranges and the models a token may access.

User groups and channel groups let you give different groups different rates, which is useful when you redistribute access to a team.

  • Expiry time per token
  • Quota per token
  • Allowed IP ranges
  • Allowed models per token

Call the endpoint from your application

Point your OpenAI-compatible client at your One API address and use one of your issued tokens as the key. The README notes that streaming is supported, so responses can be delivered incrementally.

Model mapping can redirect requested model names, but the README advises against setting it unless needed, because it rebuilds the request body instead of passing it through directly.

  • Streaming (stream mode) is supported
  • Model mapping rebuilds the request body and may drop fields not yet officially supported

Keep the service running and secure

The Docker command includes --restart always so the container restarts after a reboot. The README also gives an update command using watchtower and an Nginx reverse proxy example with HTTPS via Let's Encrypt certbot.

If you run several servers, the README describes multi-machine deployment, which requires MySQL instead of SQLite, a shared SESSION_SECRET, and Redis for caching.

  • Update command from the README: docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower -cR
  • Use HTTPS in front of the service with Nginx and certbot
  • Set SQL_DSN for heavy traffic

What people use it for

  • Give a small team one endpoint for OpenAI and Claude, with a separate token and quota for each member
  • Route requests across several provider channels with load balancing and automatic retries
  • Send alerts to phone apps by pairing with Message Pusher, as the README describes
  • Use one OpenAI-compatible client setting while switching between providers such as DeepSeek or Gemini

Frequently asked questions

Is One API free to use?

One API is open-source under the MIT licence, according to the project's licence information. You still pay the upstream model providers for their own API usage.

What do I need to run One API?

The README lists Docker as the prerequisite for the Docker install method. A manual install instead uses a downloaded executable or a build from source.

What is the default login for One API?

The initial account is username root with password 123456, as stated in the README. Change this password right after your first login.

Can I use One API with several providers at once?

Yes. The README lists support for many providers, including OpenAI, Azure, Claude, Gemini, DeepSeek and Ollama, and says clients can use the standard OpenAI API format.

How does One API compare to LiteLLM or Portkey Gateway?

Comparable projects include LiteLLM, New API and Portkey Gateway. This guide does not compare features or performance, so check each project's documentation against your needs.

Is it legal to offer One API to the public in China?

The README asks users to follow OpenAI's terms and applicable law, and asks people not to provide unregistered generative AI services to the public in China. Check local rules before you offer access to others.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

One API suits developers and small teams who want one OpenAI-compatible endpoint for several model providers and need to issue and limit keys. It is a poor fit if you only use one provider, want a fully managed hosted service, or cannot confirm that your use complies with the AI service rules that apply where you operate.

Install options & downloads