obscuraaihub 1.0.0
Multi-modal AI API Gateway - Unified interface for multiple AI providers
License: MIT
Requires Python: >=3.10
Keywords: ai, anthropic, api, gateway, gemini, llm, openai, siliconflow

# Obscura API Hub - FastAPI Backend

Multi-modal AI API Gateway with intelligent routing and provider management.

## Features

- 🔐 Token-based authentication
- 🎯 Intelligent routing strategies (auto/cost/speed/quality/balanced)
- 🔄 Automatic API key rotation
- 📊 Usage tracking and quotas
- 🚀 Multi-modal support (text, image, video, audio)
- 🔌 OpenAI-compatible API
- 💪 Provider health monitoring
- ⚡ Streaming support

## Setup

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Configure environment:
```bash
cp .env.example .env
# Edit .env with your configuration
```

3. Run the server:
```bash
# Development
python -m app.main

# Production
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

## API Endpoints

### OpenAI-Compatible Endpoints

- `POST /v1/chat/completions` - Chat completions with multimodal support
- `POST /v1/embeddings` - Text embeddings
- `GET /v1/models` - List available models
- `POST /v1/audio/transcriptions` - Audio transcription (Whisper)
- `POST /v1/images/generations` - Image generation (Lovable AI)
- `POST /v1/files` - File upload to R2

### Internal Endpoints

- `GET /health` - Health check
- `POST /internal/models/refresh` - Refresh model cache

## Multimodal Support ⭐

Supports vision, video, and audio understanding through SiliconFlow:

```python
# Vision understanding
{
    "model": "Qwen/Qwen2.5-VL-72B-Instruct",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "...", "detail": "high"}},
            {"type": "text", "text": "描述这张图片"}
        ]
    }]
}

# Video understanding
{
    "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "video_url", "video_url": {"url": "...", "max_frames": 16, "fps": 1}},
            {"type": "text", "text": "总结视频内容"}
        ]
    }]
}

# Audio understanding
{
    "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "audio_url", "audio_url": {"url": "..."}},
            {"type": "text", "text": "转录这段音频"}
        ]
    }]
}
```

## API Documentation

Once running, visit:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## Project Structure

```
backend/
├── app/
│   ├── api/              # API endpoints
│   │   ├── v1/           # v1 endpoints (OpenAI-compatible)
│   │   └── internal/     # Internal endpoints
│   ├── core/             # Core functionality (auth, routing)
│   ├── db/               # Database operations
│   ├── models/           # Pydantic models
│   ├── providers/        # LLM provider implementations
│   ├── services/         # Business logic services
│   ├── utils/            # Utilities
│   └── main.py           # FastAPI app
├── tests/                # Tests
└── requirements.txt      # Dependencies
```

## Testing

```bash
pytest tests/
```

## Environment Variables

See `.env.example` for all configuration options.

## Key Features

### Intelligent Routing
- **auto**: Balance health and priority
- **cost**: Minimize cost
- **speed**: Minimize latency
- **quality**: Maximize quality
- **balanced**: Balance all factors

### Provider Health Monitoring
- Automatic health tracking
- Failure rate calculation
- Unhealthy provider detection (>30% failure rate)

### API Key Rotation
- Round-robin rotation
- Health-based selection
- Automatic failover

### Model Binding
- Models can be bound to specific providers
- Cross-provider fallback disabled for bound models
- Automatic model discovery and caching

## License

MIT