Skip to content

API.md

Latest commit

 

History

History
211 lines (161 loc) · 6.46 KB

API.md

File metadata and controls

211 lines (161 loc) · 6.46 KB

API Reference — Personal AI Platform

Übersicht aller externen APIs und Dienste, die der Agent nutzt.

Verwendete APIs

📡 Telegram Bot API

Eigenschaft Wert
URL https://api.telegram.org/bot<TOKEN>/...
Kosten Kostenlos
Rate Limit ~30 Nachrichten/Sekunde
Datenübertragung Nachrichteninhalte, Absender-ID, Chat-ID
Authentifizierung Bot-Token im URL-Pfad

Wofür:

  • Empfangen von Nutzernachrichten
  • Senden von Antworten (Text, Markdown, HTML)
  • Bot-Profil verwalten

Token-Format: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz-123456

Token erstellen: @BotFather → /newbot

🧠 OpenRouter API

Eigenschaft Wert
URL https://openrouter.ai/api/v1/chat/completions
Kosten Pay-per-use (ab ~$0.02/1M Input-Tokens)
Rate Limit Abhängig vom Modell (kostenlose Modelle: limitiert)
Datenübertragung Prompt + Konversationsverlauf an LLM-Server
Authentifizierung Bearer Token im HTTP Header

Wofür:

  • Intent-Parser (nicht-regex-erkannte Nachrichten)
  • Wochenpläne & Zusammenfassungen
  • Insight-Generierung
  • Alle 50+ LLM-Tools

Key-Format: sk-or-v1-... (beginnt mit sk-or-v1-)

Key erstellen: openrouter.ai/keys

Datenschutz: OpenRouter leitet deine Prompts an die jeweiligen Modell-Anbieter weiter. Keine Trainingsdaten-Nutzung laut OpenRouter (Stand Mai 2026). Prüfe regelmäßig die OpenRouter Privacy Policy.

Kosten pro Modell (Auswahl)

Modell Input ($/1M Tokens) Output ($/1M Tokens) Kostenlos?
deepseek/deepseek-chat $0.14 $0.28 ❌
google/gemini-2.5-flash-lite $0.02 $0.05 ❌
meta-llama/llama-3.3-70b-instruct $0.12 $0.30 ❌
google/gemma-3-27b-it:free $0 $0 ✅
meta-llama/llama-4-maverick:free $0 $0 ✅
deepseek/deepseek-r1:free $0 $0 ✅

Bei ~30 Nachrichten/Tag und ~60% Regex-Filterung ≈ 0-0,10€/Monat.

🌤️ OpenWeatherMap API

Eigenschaft Wert
URL https://api.openweathermap.org/data/2.5/...
Kosten Kostenlos (1000 Calls/Tag)
Rate Limit 60 Calls/Minute (Free Tier)
Datenübertragung Stadtname, API-Key
Authentifizierung API-Key als Query-Parameter &appid=

Wofür:

  • Aktuelles Wetter im Morgen-Briefing
  • 5-Tage-Vorhersage
  • Wetter-Abfragen per Chat ("Wie wird das Wetter morgen?")

Key-Format: 32-stelliger Hex-String (z.B. a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6)

Key erstellen: openweathermap.org/api → Sign Up → API Keys

Aktivierungszeit: Neue Keys brauchen 10-60 Minuten.

🏠 Home Assistant REST API

Eigenschaft Wert
URL http://<HA-IP>:8123/api/...
Kosten Lokal & kostenlos
Rate Limit Keine (lokal)
Datenübertragung Nur im lokalen Netzwerk
Authentifizierung Long-Lived Access Token (Bearer)

Wofür:

  • Licht & Geräte steuern
  • Sensordaten auslesen (Temperatur, Luftfeuchtigkeit)
  • Skripte ausführen
  • Google Kalender via HA-Cache lesen
  • Temperatur/Schlaf-Korrelation

Token-Format: Langer JWT-String (~180 Zeichen, beginnt mit eyJ)

Token erstellen: HA → Profil → Sicherheit → Long-Lived Access Tokens

🌐 Web Search (DuckDuckGo / Brave)

Eigenschaft Wert
URL https://api.duckduckgo.com/...
Kosten Kostenlos
Authentifizierung Keine

Wofür:

  • Web-Suche nach aktuellen Informationen
  • Nachrichten-Schlagzeilen

📖 Wikipedia API

Eigenschaft Wert
URL https://de.wikipedia.org/w/api.php
Kosten Kostenlos
Authentifizierung Keine

Wofür:

  • Artikel-Suche und Zusammenfassung
  • "An diesem Tag"-Funktion

Datenfluss

Nutzer (Telegram)
    │
    ▼
┌─────────────────┐
│  Telegram API    │  ← Bot-Token
└────────┬────────┘
         │ Nachricht
         ▼
┌─────────────────┐
│  Regex-Parser    │  ~60% hier erkannt → direkte Antwort
└────────┬────────┘
         │ ~40% unerkannt
         ▼
┌─────────────────┐
│  LLM Intent      │  ← OpenRouter API (Prompt + Konversation)
│  Parser          │
└────────┬────────┘
         │ Tool-Aufruf
         ▼
┌─────────────────┐
│  Tool Executor   │  ← Lokale Services
│                  │  ← Optional: HA, OWM, Wikipedia, Web
└────────┬────────┘
         │ Antwort
         ▼
    Nutzer (Telegram)

🔒 API-Key Sicherheit

Der Agent behandelt alle API-Keys nach dem Zero-Trust-Prinzip:

Speicherung

  • API-Keys werden ausschließlich in .env oder Home Assistant's verschlüsseltem Storage gespeichert
  • Keine Keys im Source-Code, in Config-Dateien oder in der Datenbank
  • .env ist in .gitignore und wird niemals committed

Maskierung in Logs

  • Alle Keys werden vor dem Loggen automatisch maskiert: sk-or-v1-***abc
  • Pattern-basierte Erkennung: OpenRouter (sk-or-v1-), HA-Token (eyJ), Telegram (:AA), OWM (32-stelliger Hex)
  • Auch Substrings von Keys werden maskiert

Validierung vor Nutzung

  • API-Keys werden beim Setup-Wizard live getestet
  • Home Assistant Token: Verbindungstest gegen /api/
  • OpenRouter Key: Test-Call mit minimalem Modell
  • OpenWeatherMap Key: Test-Abfrage für Berlin (mit Timeout)
  • Ungültige Keys werden sofort erkannt und der Nutzer wird gewarnt

Rate-Limiting pro API

API Limit Timeout
OpenRouter 50 Calls/h 30s
Telegram 30 Nachrichten/min 10s
OpenWeatherMap 60 Calls/min 10s
Web Search (DuckDuckGo) 10 Suchanfragen/h 15s
Wikipedia 30 Calls/h 10s
Home Assistant Kein Limit (lokal) 5s

Alternativen

Statt Alternative Vor-/Nachteile
OpenRouter Direkt OpenAI/Anthropic API Teurer, aber stabiler
OpenRouter Lokales LLM (Ollama) Kostenlos, braucht GPU
OpenWeatherMap Wetterdienst (DWD) Kostenlos, nur Deutschland
Home Assistant openHAB, ioBroker Ähnlich, andere API
DuckDuckGo Google Custom Search Mehr Ergebnisse, kostet