🐾 NyaProxy - Universal API Proxy

📖 多言語ドキュメント / Multi-language Documentation:

• English
• 简体中文
• 日本語

<div align="center"> <img src="https://raw.githubusercontent.com/Nya-Foundation/NyaProxy/main/assets/banner.png" alt="NyaProxy Banner" width="800" /> <h3>The smart way to balance, secure, and monitor all your API interactions</h3> <div> <a href="https://github.com/Nya-Foundation/nyaproxy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Nya-Foundation/nyaproxy.svg" alt="License"/></a> <a href="https://pypi.org/project/nya-proxy/"><img src="https://img.shields.io/pypi/v/nya-proxy.svg" alt="PyPI version"/></a> <a href="https://pypi.org/project/nya-proxy/"><img src="https://img.shields.io/pypi/pyversions/nya-proxy.svg" alt="Python versions"/></a> <a href="https://pepy.tech/projects/nya-proxy"><img src="https://static.pepy.tech/badge/nya-proxy" alt="PyPI Downloads"/></a> <a href="https://hub.docker.com/r/k3scat/nya-proxy"><img src="https://img.shields.io/docker/pulls/k3scat/nya-proxy" alt="Docker Pulls"/></a> <a href="https://deepwiki.com/Nya-Foundation/NyaProxy"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"/></a> </div> <div> <a href="https://codecov.io/gh/Nya-Foundation/nyaproxy"><img src="https://codecov.io/gh/Nya-Foundation/nyaproxy/branch/main/graph/badge.svg" alt="Code Coverage"/></a> <a href="https://github.com/nya-foundation/nyaproxy/actions/workflows/scan.yml"><img src="https://github.com/nya-foundation/nyaproxy/actions/workflows/scan.yml/badge.svg" alt="CodeQL & Dependencies Scan"/></a> <a href="https://github.com/Nya-Foundation/nyaproxy/actions/workflows/publish.yml"><img src="https://github.com/Nya-Foundation/nyaproxy/actions/workflows/publish.yml/badge.svg" alt="CI/CD Builds"/></a> </div> </div>

🌈 Introduction

[!WARNING] This project is currently under active development. Documentation may not reflect the latest changes. If you encounter unexpected behavior, please consider using a previous stable version or report issues on our GitHub repository.

NyaProxy acts like a smart, central manager for accessing various online services (APIs) – think AI tools (like OpenAI, Gemini, Anthropic), image generators, or almost any web service that uses access keys. It helps you use these services more reliably, efficiently, and securely.

Here's how NyaProxy can help:

• Share the Load: Automatically spreads requests across multiple access keys so no single key gets overwhelmed (Load Balancing).
• Stay Online: If one key fails, NyaProxy automatically tries another, keeping your application running smoothly (Failover/Resilience).
• Save Costs: Optimizes how your keys are used, potentially lowering your bills.
• Boost Security: Hides your actual access keys behind the proxy, adding a layer of protection.
• Track Usage: Provides a clear dashboard to see how your keys and services are being used in real-time.

🌟 Core Capabilities

| Feature | Description | Config Reference | |-----------------------|-----------------------------------------------------------------------------|---------------------------| | 🔄 Token Rotation | Automatic key cycling across multiple providers | variables.keys | | ⚖️ Load Balancing | 5 strategies: Round Robin, Random, Least Request, Fastest Response, Weighted | load_balancing_strategy | | 🚦 Rate Limiting | Granular controls per endpoint/key with smart queuing | rate_limit | | 🕵️ Request Masking | Dynamic header substitution across multiple identity providers | headers + variables | | 📊 Real-time Metrics | Interactive dashboard with request analytics and system health | dashboard | | 🔧 Body Substitution | Dynamic JSON payload transformation using JSONPath | request_body_substitution |

📥 Quick Start

One-Click Deployment (No Fuss, No Muss!)

Pick your favorite platform and let's go!

<table> <tr> <td align="center"> <a href="https://render.com/deploy?repo=https%3A%2F%2Fgithub.com%2FNya-Foundation%2Fnyaproxy"> <img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render"> <br>Deploy to Render </a> </td> <td align="center"> <a href="https://railway.com/template/TqUoxN?referralCode=9cfC7m"> <img src="https://railway.com/button.svg" alt="Deploy on Railway"> <br>Deploy to Railway </a> </td> </tr> </table>

[!NOTE] NyaProxy automatically creates a basic working configuration when it starts. You just need to access the /config endpoint to add your API keys!

[!TIP] You can use Gemini AI Studio to get a free API key for testing. Gemini's API is OpenAI-compatible and works seamlessly with NyaProxy. Get a Gemini API key here.

Local Deployment (For the DIY Enthusiasts!)

Prerequisites

• Python 3.10 or higher
• Docker (optional, for containerized deployment)

Installation

1. Install from PyPI (the easiest way!)

pip install nya-proxy

2. Run NyaProxy

nyaproxy

...or provide your own config file:

nyaproxy --config config.yaml

3. Verify Your Setup

Visit http://localhost:8080/config to access the configuration UI.

[!IMPORTANT] If you expose this proxy to the internet, make sure to set a strong API key in your configuration to prevent unauthorized access. The first key in your API keys array will be used as the master key for accessing sensitive interfaces like the dashboard and configuration UI, while additional keys can be used for regular API requests only.

If no master API key is specified, no login page will be shown and anyone can access the dashboard and configuration UI. This is convenient for local testing but not recommended for production environments.

Check out http://localhost:8080/dashboard for the snazzy management dashboard with all your API traffic visualizations.

Detailed Deployment Guides

For step-by-step instructions tailored to beginners, check out our detailed deployment guides:

• Docker Deployment Guide - Run with Docker or Docker Compose
• PIP Installation Guide - Direct Python installation

Install from Source

# Clone the repository
git clone https://github.com/Nya-Foundation/nyaproxy.git
cd nyaproxy

# Install dependencies
pip install -e .

# Run NyaProxy
nyaproxy

Docker

docker run -d \
  -p 8080:8080 \
  # -v ${PWD}/config.yaml:/app/config.yaml \
  # -v ${PWD}/app.log:/app/app.log \
  k3scat/nya-proxy:latest

Configuration

Configuration reference can be found under Configs folder folder

# NyaProxy Configuration File
# This file contains server settings and API endpoint configurations

server:
  api_key: 
  logging:
    enabled: true
    level: debug
    log_file: app.log
  proxy:
    enabled: false
    address: socks5://username:password@proxy.example.com:1080
  dashboard:
    enabled: true
  cors:
    # Allow all origins with "*", but specify exact origins when allow_credentials is true for security
    allow_origins: ["*"]
    allow_credentials: true
    allow_methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allow_headers: ["*"]

# Default configuration applied to all API endpoints unless overridden
default_settings:
  key_variable: keys
  key_concurrency: true # mark it as true if each key can handle multiple concurrent requests, otherwise the key will be locked until the request completes
  randomness: 0.0 # Random delay of (0.0-x)s to introduce variability in request timing and avoid detection due to consistent request patterns due to rate limits
  load_balancing_strategy: round_robin
  # Path and method filtering
  allowed_paths:
    enabled: false # Set to true to enable request path filtering
    mode: whitelist # if "whitelist", only allow listed paths; if "blacklist", block listed paths
    paths:
      - "*"
  allowed_methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"] # Allowed HTTP methods for the API
  queue:
    max_size: 200
    max_workers: 10 # Maximum number of concurrent workers for processing requests
    expiry_seconds: 300
  rate_limit:
    enabled: true
    endpoint_rate_limit: 10/s # Default endpoint rate limit - can be overridden per API
    key_rate_limit: 10/m # Default key rate limit - can be overridden per API
    ip_rate_limit: 5000/d # IP-based rate limit to protect against abuse and key redistribution
    user_rate_limit: 5000/d # User-based rate limit per proxy API key defined in server section
    rate_limit_paths: 
      - "*"
  retry:
    enabled: true
    mode: key_rotation
    attempts: 3
    retry_after_seconds: 1
    retry_request_methods: [ POST, GET, PUT, DELETE, PATCH, OPTIONS ]
    retry_status_codes: [ 429, 500, 502, 503, 504 ]
  timeouts:
    request_timeout_seconds: 300

apis:
  gemini:
    # Example for OpenAI-compatible API endpoint
    name: Google Gemini API
    # Supported endpoints:
    # Gemini: https://generativelanguage.googleapis.com/v1beta/openai
    # OpenAI: https://api.openai.com/v1
    # Anthropic: https://api.anthropic.com/v1
    # DeepSeek: https://api.deepseek.com/v1
    # Mistral: https://api.mistral.ai/v1
    # OpenRouter: https://api.openrouter.ai/v1
    # Ollama: http://localhost:11434/v1
    endpoint: https://generativelanguage.googleapis.com/v1beta/openai
    aliases:
    - /gemini
    key_variable: keys
    headers:
      Authorization: 'Bearer ${{keys}}'
    variables:
      keys:
      - your_gemini_key_1
      - your_gemini_key_2
      - your_gemini_key_3
    load_balancing_strategy: least_requests