OpenAI-kompatible API - Drop-in Ersatz für OpenAI Whisper API
GPU-beschleunigt - Nutzt NVIDIA GPUs (CUDA) für schnelle Transkription
CPU Fallback - Automatischer Wechsel zu CPU wenn keine GPU verfügbar
Multi-Model Support - Unterstützung für alle Whisper Modelle (tiny bis large-v3)
Model Management - Modelle herunterladen, wechseln und löschen via Admin Panel
Default: large-v3 - Beste Qualität mit deiner RTX 3090
Web-Admin-Interface - API-Key Management, Model Management und Statistiken unter /admin
API-Key Authentifizierung - Sichere Zugriffskontrolle (Environment + Datenbank)
Cross-Platform - Docker-basiert, läuft auf Windows und Linux
Automatische Cleanup - Logs nach 30 Tagen automatisch gelöscht
Persistente Speicherung - Modelle und Daten in Docker Volumes

Architektur

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Client/App    │────▶│   FastAPI App    │────▶│  Whisper GPU    │
│  (Clawdbot etc) │     │   (Port 8000)    │     │  (large-v3)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  /admin Panel    │
                        │  - Key Mgmt      │
                        │  - Dashboard     │
                        │  - Logs          │
                        └──────────────────┘

Schnellstart

Voraussetzungen

Docker Desktop (Windows) oder Docker + docker-compose (Linux)
NVIDIA GPU mit CUDA-Unterstützung (RTX 3090)
NVIDIA Container Toolkit installiert

Installation

Repository klonen:

git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
cd whisper-api

Umgebungsvariablen konfigurieren:

cp .env.example .env
# Bearbeite .env nach deinen Wünschen

Docker-Container starten:

docker-compose up -d

Erster Start:
- Das large-v3 Modell (~3GB) wird automatisch heruntergeladen
- Dies kann 5-10 Minuten dauern
- Status überprüfen: docker-compose logs -f

Verifizierung

# Health-Check
curl http://localhost:8000/health

# API-Info
curl http://localhost:8000/v1/models

API-Dokumentation

Authentifizierung

Alle API-Endpunkte (außer /health und /admin) benötigen einen API-Key:

Authorization: Bearer sk-dein-api-key-hier

Endpunkte

POST /v1/audio/transcriptions

Transkribiert eine Audio-Datei.

Request:

curl -X POST http://localhost:8000/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-dein-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/pfad/zur/audio.mp3" \
  -F "model=large-v3" \
  -F "language=de" \
  -F "response_format=json"

Response:

{
  "text": "Hallo Welt, das ist ein Test."
}

POST /v1/audio/transcriptions (mit Timestamps)

Request:

curl -X POST http://localhost:8000/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "file=@audio.mp3" \
  -F "timestamp_granularities[]=word" \
  -F "response_format=verbose_json"

Response:

{
  "text": "Hallo Welt",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 1.5,
      "text": "Hallo Welt",
      "words": [
        {"word": "Hallo", "start": 0.0, "end": 0.5},
        {"word": "Welt", "start": 0.6, "end": 1.2}
      ]
    }
  ]
}

GET /v1/models

Liste verfügbarer Modelle.

GET /v1/available-models

Liste aller verfügbaren Whisper Modelle mit Download-Status.

Response:

{
  "models": [
    {
      "name": "large-v3",
      "size": "2.88 GB",
      "description": "Best accuracy",
      "is_downloaded": true,
      "is_active": true
    }
  ]
}

GET /v1/model-status

Aktueller Download-Status des Modells.

Response:

{
  "name": "large-v3",
  "loaded": true,
  "is_downloading": false,
  "download_percentage": 100,
  "status_message": "Model loaded successfully"
}

POST /v1/switch-model

Zu einem anderen Modell wechseln.

Request:

curl -X POST http://localhost:8000/v1/switch-model \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "model=base"

POST /v1/reload-model

Aktuelles Modell neu herunterladen.

DELETE /v1/delete-model/{model_name}

Ein heruntergeladenes Modell löschen.

GET /health

Health-Check mit GPU- und Model-Status.

Response:

{
  "status": "healthy",
  "gpu": {
    "available": true,
    "name": "NVIDIA GeForce RTX 3090",
    "vram_used": "2.1 GB",
    "vram_total": "24.0 GB"
  },
  "model": "large-v3",
  "version": "1.0.0"
}

Admin-Interface

Das Web-Interface ist erreichbar unter: http://localhost:8000/admin

Benutzername: admin (konfigurierbar in .env)
Passwort: -whisper12510- (konfigurierbar in .env)

Features

Dashboard: Übersicht über Nutzung, Performance-Statistiken, Model Download Status
API-Keys: Verwalten (erstellen, deaktivieren, löschen)
Models:
- Alle Whisper Modelle verwalten (tiny, base, small, medium, large-v1, large-v2, large-v3)
- Modelle herunterladen, aktivieren und löschen
- CPU/GPU Mode Toggle
- Model neu herunterladen
Logs: Detaillierte Transkriptions-Logs mit Filter

Konfiguration

.env.example

# Server
PORT=8000
HOST=0.0.0.0

# Whisper
WHISPER_MODEL=large-v3
WHISPER_DEVICE=cuda
WHISPER_COMPUTE_TYPE=float16

# Authentifizierung
# Mehrere API-Keys mit Komma trennen
API_KEYS=sk-dein-erster-key,sk-dein-zweiter-key
ADMIN_USER=admin
ADMIN_PASSWORD=-whisper12510-

# Daten-Retention (Tage)
LOG_RETENTION_DAYS=30

# Optional: Sentry für Error-Tracking
# SENTRY_DSN=https://...

Docker-Compose Anpassungen

services:
  whisper-api:
    # ...
    environment:
      - PORT=8000  # Änderbar
      - WHISPER_MODEL=large-v3
      - WHISPER_DEVICE=cuda  # oder 'cpu' für CPU-Modus
    volumes:
      - whisper_models:/app/models    # Persistiert Modelle (Named Volume)
      - whisper_data:/app/data        # SQLite Datenbank
      - whisper_uploads:/app/uploads  # Temporäre Uploads
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  whisper_models:
  whisper_data:
  whisper_uploads:

Migration zu Linux

Die Docker-Konfiguration ist plattformunabhängig. Für Linux:

NVIDIA Docker installieren:

# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

Projekt klonen und starten:

git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
cd whisper-api
docker-compose up -d

GPU-Passthrough verifizieren:

docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

Integration mit Clawdbot

Für die Integration in einen Clawdbot Skill:

import requests

API_URL = "http://localhost:8000/v1/audio/transcriptions"
API_KEY = "sk-dein-api-key"

def transcribe_audio(audio_path):
    with open(audio_path, "rb") as f:
        response = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": f},
            data={"language": "de"}
        )
    return response.json()["text"]

Verfügbare Modelle

Modell	Größe	Beschreibung	Geschwindigkeit	Genauigkeit
tiny	39 MB	Schnellste, niedrigste Qualität	Sehr schnell	Niedrig
base	74 MB	Gut für Tests	Schnell	Mittel
small	244 MB	Balance Speed/Qualität	Mittel	Gut
medium	769 MB	Gute Genauigkeit	Langsam	Sehr gut
large-v2	2.87 GB	Höhere Genauigkeit	Sehr langsam	Exzellent
large-v3	2.88 GB	Beste Genauigkeit (Default)	Sehr langsam	Exzellent

Empfehlungen:

Entwicklung/Tests: base oder small
Produktion: large-v3 (mit RTX 3090)
CPU-Modus: small oder medium

Performance

Mit RTX 3090 und large-v3:

1 Minute Audio: ~3-5 Sekunden Verarbeitungszeit
VRAM-Nutzung: ~10 GB
Batch-Verarbeitung: Möglich für parallele Requests

Mit CPU und small:

1 Minute Audio: ~30-60 Sekunden Verarbeitungszeit
RAM-Nutzung: ~1 GB

Troubleshooting

GPU nicht erkannt / Automatischer CPU Fallback

Falls keine GPU erkannt wird, schaltet die API automatisch auf CPU-Modus um:

# NVIDIA Container Toolkit prüfen
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

# Logs prüfen - sollte "GPU not available, falling back to CPU mode" zeigen
docker-compose logs whisper-api

Manueller Wechsel: Über Admin Panel (/admin/models) oder API:

curl -X POST http://localhost:8000/v1/switch-device \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "device=cpu"

Modell-Download Status anzeigen

Dashboard: Zeigt Download-Fortschritt in Echtzeit
API: GET /v1/model-status für aktuellen Status
Logs: docker-compose logs -f zeigt Download-Progress

Modell-Download langsam

# Im Admin Panel unter Models ein kleineres Modell wählen (z.B. base, small)
# Oder via API:
curl -X POST http://localhost:8000/v1/switch-model \
  -H "Authorization: Bearer sk-dein-api-key" \
  -F "model=base"

Port belegt

# Port in .env ändern
PORT=8001

Backup

Wichtige Daten (Docker Named Volumes):

whisper_data - SQLite Datenbank (API-Keys, Logs)
whisper_models - Heruntergeladene Whisper-Modelle
./.env - Konfiguration

# Backup erstellen
docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine sh -c "tar czf /backup/whisper-api-backup.tar.gz -C / data models"

# Oder komplettes Backup inkl. .env
cp .env .env.backup
docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine tar czf /backup/whisper-api-full-backup.tar.gz -C / data models

Backup wiederherstellen

# Backup extrahieren
docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine sh -c "cd / && tar xzf /backup/whisper-api-backup.tar.gz"

Lizenz

MIT License - Siehe LICENSE Datei

Support

Bei Problemen:

Logs prüfen: docker-compose logs -f
Health-Check: curl http://localhost:8000/health
Issue auf Gitea erstellen

Erstellt für: b0rborad @ ragtag.rocks
Hardware: Dual RTX 3090 Setup
Zweck: Clawdbot Skill Integration

README.md

Whisper API

Features

Architektur

Schnellstart

Voraussetzungen

Installation

Verifizierung

API-Dokumentation

Authentifizierung

Endpunkte

POST /v1/audio/transcriptions

POST /v1/audio/transcriptions (mit Timestamps)

GET /v1/models

GET /v1/available-models

GET /v1/model-status

POST /v1/switch-model

POST /v1/reload-model

DELETE /v1/delete-model/{model_name}

GET /health

Admin-Interface

Login

Features

Konfiguration

.env.example

Docker-Compose Anpassungen

Migration zu Linux

Integration mit Clawdbot

Verfügbare Modelle

Performance

Troubleshooting

GPU nicht erkannt / Automatischer CPU Fallback

Modell-Download Status anzeigen

Modell-Download langsam

Port belegt

Backup

Backup wiederherstellen

Lizenz

Support