uni-api

<p align="center"> <a href="https://t.me/uni_api"> <img src="https://img.shields.io/badge/Join Telegram Group-blue?&logo=telegram"> </a> <a href="https://hub.docker.com/repository/docker/yym68686/uni-api"> <img src="https://img.shields.io/docker/pulls/yym68686/uni-api?color=blue" alt="docker pull"> </a> </p>

English | Chinese

Introduction

For personal use, one/new-api is too complex with many commercial features that individuals don't need. If you don't want a complicated frontend interface and prefer support for more models, you can try uni-api. This is a project that unifies the management of large language model APIs, allowing you to call multiple backend services through a single unified API interface, converting them all to OpenAI format, and supporting load balancing. Currently supported backend services include: OpenAI, Anthropic, Gemini, Vertex, Azure, AWS, xai, Cohere, Groq, Cloudflare, OpenRouter, 0-0.pro and more.

✨ Features

• No front-end, pure configuration file to configure API channels. You can run your own API station just by writing a file, and the documentation has a detailed configuration guide, beginner-friendly.
• Unified management of multiple backend services, supporting providers such as OpenAI, Deepseek, OpenRouter, and other APIs in OpenAI format. Supports OpenAI Dalle-3 image generation.
• Simultaneously supports Anthropic, Gemini, Vertex AI, Azure, AWS, xai, Cohere, Groq, Cloudflare, 0-0.pro. Vertex simultaneously supports Claude and Gemini API.
• Support OpenAI, Anthropic, Gemini, Vertex, Azure, AWS, xai native tool use function calls.
• Support OpenAI, Anthropic, Gemini, Vertex, Azure, AWS, xai native image recognition API.
• Support three types of load balancing.
  1. Supports channel-level weighted load balancing, allowing requests to be distributed according to different channel weights. It is not enabled by default and requires configuring channel weights.
  2. All APIs support channel-level sequential load balancing, enhancing the immersive translation experience. It is not enabled by default and requires configuring SCHEDULING_ALGORITHM as round_robin.
  3. Support automatic API key-level round-robin load balancing for multiple API Keys in a single channel.
• Support automatic retry, when an API channel response fails, automatically retry the next API channel.
• Support channel cooling: When an API channel response fails, the channel will automatically be excluded and cooled for a period of time, and requests to the channel will be stopped. After the cooling period ends, the model will automatically be restored until it fails again, at which point it will be cooled again.
• Support fine-grained model timeout settings, allowing different timeout durations for each model.
• Support fine-grained permission control. Support using wildcards to set specific models available for API key channels.
• Support rate limiting, you can set the maximum number of requests per minute as an integer, such as 2/min, 2 times per minute, 5/hour, 5 times per hour, 10/day, 10 times per day, 10/month, 10 times per month, 10/year, 10 times per year. Default is 60/min.
• Supports multiple standard OpenAI format interfaces: /v1/chat/completions, /v1/responses, /v1/images/generations, /v1/embeddings, /v1/audio/transcriptions, /v1/audio/speech, /v1/moderations, /v1/models.
• Support OpenAI moderation moral review, which can conduct moral reviews of user messages. If inappropriate messages are found, an error message will be returned. This reduces the risk of the backend API being banned by providers.

Usage method

To start uni-api, a configuration file must be used. There are two ways to start with a configuration file:

1. The first method is to use the CONFIG_URL environment variable to fill in the configuration file URL, which will be automatically downloaded when uni-api starts.
2. The second method is to mount a configuration file named api.yaml into the container.

Method 1: Mount the api.yaml configuration file to start uni-api

One-click deployment:

You must fill in the configuration file in advance to start uni-api, and you must use a configuration file named api.yaml to start uni-api, you can configure multiple models, each model can configure multiple backend services, and support load balancing. Below is an example of the minimum api.yaml configuration file that can be run:

providers:
  - provider: provider_name # Service provider name, such as openai, anthropic, gemini, openrouter, can be any name, required
    base_url: https://api.your.com/v1/chat/completions # Backend service API address, required
    api: sk-YgS6GTi0b4bEabc4C # Provider's API Key, required, automatically uses base_url and api to get all available models through the /v1/models endpoint.
  # Multiple providers can be configured here, each provider can configure multiple API Keys, and each provider can configure multiple models.
api_keys:
  - api: sk-Pkj60Yf8JFWxfgRmXQFWyGtWUddGZnmi3KlvowmRWpWpQxx # API Key, user request uni-api requires API key, required
  # This API Key can use all models, that is, it can use all models in all channels set under providers, without needing to add available channels one by one.

Detailed advanced configuration of api.yaml:

providers:
  - provider: provider_name # Service provider name, such as openai, anthropic, gemini, openrouter, can be any name, required
    base_url: https://api.your.com/v1/chat/completions # Backend service API address, required
    api: sk-YgS6GTi0b4bEabc4C # Provider's API Key, required
    model: # Optional, if model is not configured, all available models will be automatically obtained through base_url and api via the /v1/models endpoint.
      - gpt-5.2 # Usable model name, required
      - claude-sonnet-4-5-20250929: claude-sonnet-4-5 # Rename model, claude-sonnet-4-5-20250929 is the provider's model name, claude-sonnet-4-5 is the renamed name, you can use a simple name to replace the original complex name, optional
      - dall-e-3
    exclude_endpoints: # Optional. Exact request paths this provider should skip.
      - /v1/responses/compact
    preferences:
      max_request_body_bytes: 20000000 # Optional. Skip this provider when the incoming JSON request body is larger than this many bytes. Numeric values and strings like "20MB" or "20MiB" are supported.

  - provider: anthropic
    base_url: https://api.anthropic.com/v1/messages
    api: # Supports multiple API Keys, multiple keys automatically enable polling load balancing, at least one key, required
      - sk-ant-api03-bNnAOJyA-xQw_twAA
      - sk-ant-api02-bNnxxxx
    model:
      - claude-sonnet-4-5-20250929: claude-sonnet-4-5 # Rename model, claude-sonnet-4-5-20250929 is the provider's model name, claude-sonnet-4-5 is the renamed name, you can use a simple name to replace the original complex name, optional
      - claude-sonnet-4-5-20250929: claude-sonnet-4-5-think # Rename model, claude-sonnet-4-5-20250929 is the provider's model name, claude-sonnet-4-5-think is the renamed name, if "think" is in the renamed name, it will be automatically converted to claude think model, default think token limit is 4096. Optional
    tools: true # Whether to support tools, such as generating code, generating documents, etc., default is true, optional
    preferences:
      post_body_parameter_overrides: # Support customizing request body parameters
        # Apply order: global parameters and global __remove__ first, then model-specific parameters and model-specific __remove__; model-specific settings take precedence.
        __remove__: # Optional. Remove top-level request body fields; accepts a string or a list. If omitted, nothing is removed.
          - response_format
        claude-sonnet-4-5-think: # Add custom request body parameters to the model claude-sonnet-4-5-think
          __remove__:
            - temperature
          tools:
            - type: code_execution_20250522 # Add code_execution tool to the model claude-sonnet-4-5-think
              name: code_execution
            - type: web_search_20250305 # Add web_search tool to the model claude-sonnet-4-5-think, max_uses means to use up to 5 times
              name: web_search
              max_uses: 5

  - provider: gemini
    base_url: https://generativelanguage.googleapis.com/v1beta # base_url supports v1beta/v1, only for Gemini model use, required
    api: # Supports multiple API Keys, multiple keys automatically enable polling load balancing, at least one key, required
      - AIzaSyAN2k6IRdgw123
      - AIzaSyAN2k6IRdgw456
      - AIzaSyAN2k6IRdgw789
    model:
      - gemini-3-pro-preview: gemini-3-pro
      - gemini-2.5-flash: gemini-2.5-flash # After renaming, the original model name gemini-2.5-flash cannot be used, if you want to use the original name, you can add the original name in the model, just add the line below to use the original name
      - gemini-2.5-flash
      - gemini-pro-latest: gemini-2.5-pro-search # To enable search for a model, rename it with the -search suffix and set custom request body parameters for this model in `post_body_parameter_overrides`.
      - gemini-2.5-flash: gemini-2.5-flash-think-24576-search # To enable search for a model, rename it with the -search suffix and set custom request body parameters for this model in post_body_parameter_overrides. Additionally, you can customize the inference budget using -think-number. These options can be used together or separately.
      - gemini-2.5-flash: gemini-2.5-flash-think-0 # Support to rename models with -think-number suffix to enable search, if the number is 0, it means to close the reasoning.
      - gemini