README.md

metadata

title: APIarium
emoji: 🐝
colorFrom: blue
colorTo: green
sdk: docker
app_port: 1111

🐝 APIarium

OpenAI-compatible LLM API gateway with multi-provider routing, encrypted configuration, and admin management.

Features

• Multi-Model Routing — Route requests to multiple LLM providers through a unified OpenAI-compatible API
• Encrypted Config — Sensitive values (API keys, tokens) stored as AES-256-GCM encrypted blobs in the repo
• Admin Dashboard — Web UI for managing API keys, providers, and balance monitoring
• Cloudflare Turnstile — Bot protection for admin endpoints
• VPN Detection — Free VPN/proxy detection via proxycheck.io
• IP Blocking — Built-in IP blocklist support
• GitHub Gist Storage — API key persistence via encrypted GitHub Gists
• HuggingFace Dataset Logging — Request/response logging to HF Datasets
• Dynamic Providers — Add/remove upstream providers at runtime

Architecture

Client → APIarium (FastAPI) → Multiple LLM Upstreams
                  ↓
           Admin Panel (Turnstile protected)
                  ↓
           GitHub Gist (encrypted key storage)
           HF Dataset (request logging)

Supported Models

Models are exposed as aliases through the /v1/models endpoint. Each alias routes to one or more upstream providers configured in app/config.py.

API Endpoints

Proxy

Method	Endpoint	Description
POST	/v1/chat/completions	OpenAI-compatible chat completion
POST	/v1/completions	Text completions
GET	/v1/models	List available models

Admin

Method	Endpoint	Description
GET	/admin	Admin dashboard (Turnstile protected)
GET	/admin/keys	API key management
GET	/admin/providers	Provider management
GET	/admin/balance	Balance monitoring
POST	/admin/verify-turnstile	Turnstile token verification

Health

Method	Endpoint	Description
GET	/health	Health check

Environment Variables

Variable	Required	Description
AES_KEY	✅ Yes	Base64-encoded 32-byte AES-256 key for decrypting config secrets
HF_TOKEN	Optional	HuggingFace token for dataset logging
TURNSTILE_SITE_KEY	Optional	Cloudflare Turnstile site key for admin protection
TURNSTILE_SECRET_KEY	Optional	Cloudflare Turnstile secret key for server-side verification
UPSTREAM_API_KEY	Optional	Fallback API key for upstreams without specific keys

Configuration

Encrypted Secrets

Sensitive values are encrypted using AES-256-GCM and stored in app/config.py:

# Encrypt a value locally
python encrypt_config.py "your-secret-value"
# Output: enc:v1:nonce:ciphertext

In code:

GITHUB_TOKEN = _decrypt("enc:v1:...")

The AES_KEY environment variable must be set at runtime for decryption.

Generating an AES Key

import base64, os
key = base64.b64encode(os.urandom(32)).decode()
print(key)

Store this value as the AES_KEY secret in your deployment environment.

Upstream Routing

Models are mapped to upstream endpoints in the UPSTREAMS dict inside app/config.py:

UPSTREAMS = {
    "model-alias": [
        {"url": "https://upstream.example.com/v1", "model": "real-model-name"},
    ],
}

Per-Upstream API Keys

UPSTREAM_API_KEYS = {
    "https://upstream-a.example.com/v1": "sk-...",
    "https://upstream-b.example.com/v1": "sk-...",
}

If no key is configured for a URL, the UPSTREAM_API_KEY env var is used as fallback.

Balance Endpoints

Provider balance checking via BALANCE_ENDPOINTS:

BALANCE_ENDPOINTS = {
    "provider-name": "https://api.provider.com/v1/balance",
}

Local Development

# Clone
git clone https://huggingface.co/spaces/rnilkyway/APIarium
cd APIarium

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set required env vars
export AES_KEY="your-base64-encoded-32-byte-key"

# Run
uvicorn app.index:app --host 0.0.0.0 --port 1111 --reload

Docker

docker build -t apiarium .
docker run -p 1111:1111 -e AES_KEY="your-key" apiarium

Deployment on HuggingFace Spaces

This space runs on HuggingFace Spaces using the Docker SDK (app_port: 1111).

Setting Secrets

1. Go to Space Settings → Variables and secrets
2. Add AES_KEY with your base64-encoded 32-byte key
3. Optionally add TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY
4. Optionally add HF_TOKEN for dataset logging

Triggering a Rebuild

Any commit to the main branch automatically triggers a rebuild.

Project Structure

APIarium/
├── app/
│   ├── index.py        # Main FastAPI application
│   ├── config.py       # Configuration & encrypted secrets
│   └── templates.py    # HTML templates for admin UI
├── encrypt_config.py   # AES encryption utility
├── test_gist.py        # Gist storage integration tests
├── Dockerfile          # Container definition
├── requirements.txt    # Python dependencies
└── README.md           # This file

Security

• All sensitive config values are AES-256-GCM encrypted at rest
• Master key authentication for admin access
• Cloudflare Turnstile bot protection on admin endpoints
• Free VPN/proxy detection and automatic blocking
• IP blocklist support
• CORS configured for allowed origins
• Encrypted GitHub Gist storage for API key persistence