taazkareem/google-lens-scraper

Google Lens Agenten-Skill

Dieses Skill ermöglicht einem KI-Agenten, Rückwärtssuchen durchzuführen, optische Zeichenerkennung (OCR)-Texte zu extrahieren, visuelle Entitäten zu erkennen und Produktmatches/Preise über Google Lens zu finden.

Voraussetzungen & Installation

Falls google-lens noch nicht in der Umgebung installiert ist, installieren Sie das Paket und laden Sie den stealth Chromium-Browser-Binary herunter:

pip install google-lens-scraper
patchright install chromium

Hinweis: Der schnelle OCR-Modus (--ocr-only) erfordert nur das Python-Paket und funktioniert sofort ohne Herunterladen von Chromium-Binaries.

Schnellstart-Rezepte

1. Rückwärtssuche & Visuelle Intelligenz (Standard-Modus)

Um passende Produkte, Webquellen, normalisierte Preisanalysen und multimodale Attributanalysen zu finden:

google-lens search "<bild-url-oder-pfad>" --json-output

Hinweis: Standardmäßig führt google-lens search automatisch E-Commerce-Preisnormalisierung (--enrich) und tiefgehende multimodale Attributanalyse (--analyze) über Gemini 3.8 Flash durch, falls GEMINI_API_KEY vorhanden ist.

KI-Agent In-Context-Fallback-Strategie: Falls results.analysis null ist (weil GEMINI_API_KEY nicht in der Host-Umgebung konfiguriert ist), sollten Sie (der KI-Agent) das Abfragebild und die zurückgegebenen visual_matches direkt in Ihrem eigenen Kontext analysieren, um Produktattribute (Marke, Modell-Silhouette, Materialien, Zustand, geschätzter UVP, Authentizitätshinweise) abzuleiten. Dies garantiert eine reibungslose Nutzung ohne zusätzliche API-Keys.

2. Nano Banana Pro 8K KI-Studio-Packshot-Generierung

Um ein ultra-scharfes 8K-Kommerz-Katalog-Packshot auf einem makellosen weißen Hintergrund aus einem Referenzbild zu synthetisieren:

google-lens search "<bild-url-oder-pfad>" --studio --studio-output ./packshot.png

Sie können optional einen benutzerdefinierten Prompt angeben:

google-lens search "<bild-url-oder-pfad>" --studio --studio-prompt "8K-Studio-Katalogaufnahme auf schwarzem, gebürstetem Granit mit weicher, dramatischer Kantenbeleuchtung"

3. Schneller OCR- & Objekterkennungs-Pfad (Unter einer Sekunde, Kein CAPTCHA)

Zum Extrahieren von Text oder Begrenzungsrahmen aus einem Bild (verwendet Chromium-Protobuf-Endpunkt, kein Browser-Overhead):

google-lens search "<bild-url-oder-pfad>" --ocr-only --json-output

4. E-Commerce- & Wiederverkaufs-Arbitrage-Intelligenz (Pro)

Um saubere kanonische URLs, normalisierte Preisspannen (Min/Max/Durchschnitt) zu ermitteln und den günstigsten verifizierten Verkäufer („Best Deal“) zu identifizieren:

google-lens search "<bild-url-oder-pfad>" --enrich --json-output

Um angereicherte Handelsdaten direkt als sauberes JSON zu exportieren:

google-lens search "<bild-url-oder-pfad>" --export-json deals.json

5. Echtzeit-Token- & Kostenbuchhaltung

Jeder Gemini-API-Aufruf (Gemini 3.8 Flash und Nano Banana Pro) wird automatisch mit dem integrierten gemini-cost-calculator verfolgt. Bei Aufruf über CLI oder SDK gibt results.cost die genaue Token-Nutzung und die finanziellen Kosten in USD zurück:

"cost": {
  "model": "gemini-3.8-flash",
  "calls_count": 1,
  "tokens": { "prompt": 450, "output": 180, "total": 630 },
  "cost_usd": { "total": 0.001013 }
}

6. Lizenzaktivierung & Einrichtung (Pro)

Pro-Funktionen (Marktpreis-Intelligenz, saubere URLs, JSON-Export, Studio-Packs) erfordern eine aktive Polar.sh-Lizenz.

Lizenz kaufen (Browser):

google-lens buy pro
# Oder einen Plan angeben:
google-lens buy --plan annual

Öffnet die Polar.sh-Checkout-Seite direkt in Ihrem Browser, um einen Plan (Lebenslang, Jährlich oder Monatlich) auszuwählen.

Im Terminal aktivieren:

google-lens pro activate "<ihr-polar-license-key>"
# Oder interaktiv ausführen:
google-lens pro activate
# Oder Umgebungsvariable setzen:
export LENS_LICENSE_KEY="<ihr-polar-license-key>"

Lizenzstatus überprüfen:

google-lens pro status

Auf diesem Rechner deaktivieren:

google-lens pro deactivate

7. Google AI Studio-Key (Optional, Nur für --studio)

Google Lens Scraper benötigt keinen Gemini-API-Key für reguläre Suchen oder Produktattribute – diese werden nativ aus den Lens-Metadaten ohne Reibungsverluste abgeleitet.

Um 8K-KI-Studio-Packshots (--studio) zu synthetisieren, konfigurieren Sie Ihren Schlüssel einmalig:

google-lens setup-ai --key "<ihr-gemini-api-key>"
# Oder Umgebungsvariable setzen:
export GEMINI_API_KEY="<ihr-gemini-api-key>"

8. Sitzungsstatus & Google-Authentifizierung

Google Lens erfordert eine authentifizierte Google-Sitzung für vollständige visuelle Treffer und um /sorry/index-Ratenbegrenzungen zu vermeiden:

google-lens status

Falls nicht authentifiziert und in einer interaktiven Desktop-Umgebung:

google-lens login

Für Headless-/Cloud-/CI-Umgebungen übergeben Sie den Sitzungsstatus über eine Umgebungsvariable:

export LENS_STORAGE_STATE_JSON="<base64-oder-raw-json-sitzungsstatus>"

---

Gebündelte Hilfsskripte

Für programmatische Workflows und Batch-Operationen verwenden Sie die gebündelten Skripte im Verzeichnis scripts/. Diese Skripte enthalten PEP 723-Inline-Abhängigkeitsmetadaten.

Einzelbildsuche & Filterung (scripts/search_image.py)

Durchsuchen Sie ein Bild mit integrierter Filterung nach Preis, Ergebnisanzahl oder Modus:

# Grundlegende Suche mit JSON-Ausgabe
python3 scripts/search_image.py "https://example.com/photo.jpg" --json

# Visuelle Treffer filtern (z. B. max. 5 Ergebnisse)
python3 scripts/search_image.py "pfad/zum/bild.png" --max-results 5 --json

# Schnelle OCR-Extraktion
python3 scripts/search_image.py "pfad/zur/quittung.jpg" --ocr-only --json

Batch-Bildverarbeitung (scripts/batch_search.py)

Verarbeiten Sie ein Verzeichnis mit Bildern oder eine Liste von URLs asynchron:

# Alle Bilder in einem Verzeichnis verarbeiten
python3 scripts/batch_search.py --dir ./bilder/ --output ./batch_ergebnisse.json

# Liste von URLs aus einer Datei verarbeiten
python3 scripts/batch_search.py --urls-file ./bild_urls.txt --output ./batch_ergebnisse.json --concurrency 3

---

Ausgabe interpretieren

Wenn --json-output verwendet wird, folgt die JSON-Nutzlast dieser Struktur:

{
  "query": "https://example.com/artikel.jpg",
  "ocr_text": "Erkannter Text aus dem Bild...",
  "knowledge_graph": {
    "title": "Identifizierter Objekt-/Entitätsname",
    "subtitle": "Klassifikation (z. B. Schuhe / Pflanze)",
    "description": "Kurze enzyklopädische Beschreibung",
    "website": "https://..."
  },
  "visual_matches": [
    {
      "title": "Produkttitel",
      "link": "https://store.com/artikel",
      "source": "Store-Name",
      "price": "99,00 €",
      "thumbnail": "https://..."
    }
  ],
  "detected_objects": [
    {
      "id": "objekt_1",
      "bounding_box": {
        "center_x": 0.5,
        "center_y": 0.5,
        "width": 0.3,
        "height": 0.4
      }
    }
  ]
}

---

Fehlerbehebung & Best Practices

1. Bot-Abwehr (HTTP 429 / CAPTCHA): Falls visuelle Treffer-Anfragen ratenbegrenzt werden, wechseln Sie zu --ocr-only (garantiert keine CAPTCHAs) oder authentifizieren Sie sich über google-lens login oder LENS_STORAGE_STATE_JSON.
2. Lokale Bilder: Lokale Dateipfade (.png, .jpg, .jpeg, .webp, .bmp, .gif) werden automatisch an den Google-Schnellupload-Endpunkt hochgeladen.
3. Headless-Ausführung: Suchen werden standardmäßig headless ausgeführt. In Debugging-Umgebungen übergeben Sie --no-headless, um den Browser zu inspizieren.

Vollständige CLI-Flags, Konfigurationsparameter und detaillierte JSON-Schemas finden Sie in references/REFERENCE.md.