One API Setup Guide: Manage LLM Keys and Access 100+ AI Models

Managing API keys across a dozen different AI providers is chaotic. One API simplifies the process. It is a lightweight distribution system that utilizes the standard OpenAI API format while routing requests to over a hundred models—ranging from Claude and Gemini to DeepSeek and Qwen. This provides a single endpoint, a unified token system, and a centralized dashboard to track your usage and spending.

Models Supported

The platform supports an extensive list of providers, including:

• OpenAI ChatGPT (and Azure OpenAI)
• Anthropic Claude (including AWS Bedrock)
• Google PaLM2 and Gemini
• Mistral
• ByteDance Doubao (Volcano Engine)
• Baidu Wenxin Yiyan
• Alibaba Tongyi Qwen
• iFlytek Spark
• Zhipu ChatGLM
• 360 Brain
• Tencent Hunyuan
• Moonshot, Baichuan, MiniMax, Groq, Ollama, and many others

If a service offers an API, One API can likely integrate with it.

Key Features

• Proxy and Mirror Support: Easily configure third-party proxies without complex workarounds.
• Load Balancing: Automatically distribute requests across multiple channels to ensure stability.
• Streaming: Full compatibility with Server-Sent Events (SSE) for real-time typing indicators.
• Multi-Server Deployment: Scale horizontally to accommodate traffic spikes.
• Granular Token Management: Set expiration dates, quotas, allowed IP ranges, and specific model access for every token.
• Redemption System: Generate and export bulk redemption codes to allow users to top up their accounts.
• Channel Grouping: Assign distinct consumption multipliers to different user groups.
• Model Mapping: Transparently redirect requests to alternative models by rewriting the request body.
• Automatic Retries: Failed requests are automatically rerouted to ensure successful delivery.
• Image Generation: Full support for DALL-E API calls.
• Cloudflare AI Gateway: Integration is as simple as entering your gateway URL.
• Custom Branding: Personalize the system name, logo, footer, and landing pages.
• Turnstile Verification: Integrated Cloudflare Turnstile support for secure user flows.
• Flexible Login Options: Supports Email, Feishu, GitHub, and WeChat Official Accounts (requires a separate server).
• Dynamic Themes: Change the UI look instantly by updating the THEME variable.
• Real-time Alerts: Pipe system warnings directly to your phone via Message Pusher.

Deployment

Docker Deployment (The Recommended Way)

For SQLite:

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

For MySQL:

Add -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" to the command and adjust the connection string to match your database credentials.

If you encounter issues pulling the image, use the GitHub Container Registry mirror: ghcr.io/songquanpeng/one-api.

To update the container:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower -cR

Nginx Configuration

server{
   server_name openai.justsong.cn;

   location / {
          client_max_body_size  64m;
          proxy_http_version 1.1;
          proxy_pass http://localhost:3000;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-For $remote_addr;
          proxy_cache_bypass $http_upgrade;
          proxy_set_header Accept-Encoding gzip;
          proxy_read_timeout 300s;
   }
}

After configuring Nginx, secure your instance with Let's Encrypt:

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
sudo service nginx restart

The initial login credentials are root and 123456. You should change these immediately upon first login.

One-Click Installation via BT Panel

1. Install BT Panel version 9.2.0 or later.
2. Navigate to the Docker tab and install the Docker service if prompted.
3. Search for One-API in the App Store, click install, and configure your domain name.

Docker Compose

docker-compose up -d
docker-compose ps

Persistent data will be stored in ./data/mysql.

Building from Source

git clone https://github.com/songquanpeng/one-api.git
cd one-api/web/default
npm install
npm run build
cd ../..
go mod download
go build -ldflags "-s -w" -o one-api

To run the binary:

chmod u+x one-api
./one-api --port 3000 --log-dir ./logs

Distributed Multi-Server Setup

1. Ensure all nodes use the same SESSION_SECRET.
2. Use a centralized MySQL instance via SQL_DSN.
3. Set NODE_TYPE=slave on all secondary servers.
4. Enable Redis and configure SYNC_FREQUENCY to reduce database load.
5. Point the FRONTEND_BASE_URL on slave nodes to the primary server.
6. Configure the REDIS_CONN_STRING on each node.

Deploying to Cloud Platforms

• Sealos: Offers one-click deployment with servers located outside mainland China. If you see a 404 error immediately after deployment, wait 3–5 minutes for the service to initialize.
• Zeabur: Fork the repository, create a MySQL service, define the PORT and SQL_DSN environment variables, and deploy.
• Render: You can deploy the Docker image directly through the Render dashboard.

Client Integrations

One API works with most OpenAI-compatible clients:

ChatGPT Next Web:

docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-web

Input your One API address (e.g., https://openai.justsong.cn) and your generated token in the settings.

ChatGPT Web:

docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.justsong.cn -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-web

QChatGPT (QQ Bot):
Modify data/provider.json, set requester.openai-chat-completions.base-url to your One API instance, and input your token under keys.openai.

Configuration Essentials

Create a .env file from the provided .env.example. Essential variables include:

• REDIS_CONN_STRING: Enables Redis for caching.
• SESSION_SECRET: Ensures user sessions remain valid after service restarts.
• SQL_DSN: Configures the connection for MySQL or PostgreSQL instead of the default SQLite.

Useful command-line flags include --port, --log-dir, --version, and --help.

How to Use It

1. Add Channels: Go to the Channels page to input your provider API keys.
2. Create Tokens: Generate a personal token in the Tokens page.
3. Connect Clients: Point any OpenAI-compatible client to https://your-domain.com and use your One API token as the API key.

To route a request to a specific channel, append the channel ID to your token: Authorization: Bearer YOUR_TOKEN-CHANNEL_ID. (Note: This is restricted to admin-created tokens.)

Common Issues and Troubleshooting

• Quota Calculation: The formula is: Quota = Group Multiplier × Model Multiplier × (Prompt Tokens + Completion Tokens × Completion Multiplier). For context, the default completion multiplier for GPT-3.5 is 1.33, and for GPT-4, it is 2.
• "Insufficient quota" error: Even if the account has a balance, check the specific token quota. They are managed independently.
• "No available channels": Verify that the specific model is enabled for that channel and that the channel is assigned to the correct user group.
• Channel test returns invalid character '<': This usually indicates that the IP address or proxy is being blocked by Cloudflare's security layers.
• "Failed to fetch" in ChatGPT Next Web: Do not set the BASE_URL incorrectly. Verify your API address and ensure you are using the correct protocol (HTTPS vs. HTTP).
• "Group load saturated": This means the upstream provider has returned a 429 (Too Many Requests) error.
• Data loss after upgrade: If using SQLite, ensure you have mounted a persistent volume for one-api.db. MySQL users are generally unaffected by container updates.
• "Database consistency broken": This occurs if a channel is deleted but orphaned records remain in the ability table. These records must be cleared manually from the database.

One API transforms a fragmented collection of AI subscriptions into a single, manageable interface. Once configured, you can add keys as needed and stop juggling multiple endpoints.