taazkareem/google-lens-scraper

Compétence Agent Google Lens

Cette compétence permet à un agent IA d'exécuter des recherches d'image inversée, d'extraire du texte par reconnaissance optique de caractères (OCR), de détecter des entités visuelles et de trouver des correspondances commerciales et des prix via Google Lens.

Prérequis et Installation

Si google-lens n'est pas encore installé dans l'environnement, installez le package et téléchargez le binaire Chromium furtif :

pip install google-lens-scraper
patchright install chromium

Remarque : Le mode OCR rapide (--ocr-only) nécessite uniquement le package Python et fonctionne immédiatement sans télécharger les binaires Chromium.

Recettes de démarrage rapide

1. Recherche d'image inversée et Intelligence Visuelle (Mode par défaut)

Pour trouver des produits correspondants, des sources web, des analyses de prix normalisées et une analyse d'attributs multimodale :

google-lens search "<url-ou-chemin-image>" --json-output

Remarque : Par défaut, google-lens search exécute automatiquement la normalisation des prix e-commerce (--enrich) et une analyse approfondie des attributs multimodaux (--analyze) via Gemini 3.8 Flash si GEMINI_API_KEY est présente.

Stratégie de repli contextuelle pour l'agent : Si results.analysis est null (car GEMINI_API_KEY n'est pas configurée dans l'environnement hôte), vous (l'agent IA) devez inspecter l'image de requête et les visual_matches retournées directement dans votre propre contexte de conversation pour déduire les attributs du produit (marque, silhouette du modèle, matériaux, état, prix de vente conseillé estimé, indices d'authenticité). Cela garantit zéro friction pour les utilisateurs sans nécessiter de clés API supplémentaires.

2. Génération de Packshot Studio Nano Banana Pro 8K IA

Pour synthétiser un packshot de catalogue commercial ultra-net en 8K sur fond blanc immaculé à partir d'une image de référence :

google-lens search "<url-ou-chemin-image>" --studio --studio-output ./packshot.png

Vous pouvez éventuellement fournir un prompt personnalisé :

google-lens search "<url-ou-chemin-image>" --studio --studio-prompt "Plan de catalogue studio 8K sur granit brossé noir avec éclairage dramatique doux en contre-jour"

3. Détection OCR et d'objets rapide (Moins d'une seconde, sans CAPTCHA)

Pour extraire du texte ou des boîtes englobantes d'une image (utilise le point de terminaison Protobuf de Chromium, zéro surcharge du navigateur) :

google-lens search "<url-ou-chemin-image>" --ocr-only --json-output

4. Intelligence E-commerce et Arbitrage de Revente (Pro)

Pour résoudre les URL canoniques propres, les fourchettes de prix normalisées (min/max/moyenne) et identifier le vendeur vérifié le moins cher ("Meilleure affaire") :

google-lens search "<url-ou-chemin-image>" --enrich --json-output

Pour exporter les données commerciales enrichies directement en JSON propre :

google-lens search "<url-ou-chemin-image>" --export-json deals.json

5. Suivi en temps réel des jetons et des coûts

Chaque invocation de l'API Gemini (Gemini 3.8 Flash et Nano Banana Pro) est automatiquement suivie à l'aide du gemini-cost-calculator intégré. Lors de l'appel via CLI ou SDK, results.cost renvoie l'utilisation exacte des jetons et le coût financier en USD :

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

6. Activation de la licence et Configuration (Pro)

Les fonctionnalités Pro (intelligence des prix du marché, URL propres, export JSON, packs studio) nécessitent une licence active Polar.sh.

Acheter une licence (Navigateur) :

google-lens buy pro
# Ou spécifier un plan :
google-lens buy --plan annual

Ouvre la page de paiement Polar.sh directement dans votre navigateur pour choisir un plan (À vie, Annuel ou Mensuel).

Activer dans le terminal :

google-lens pro activate "<votre-clé-de-licence-polar>"
# Ou exécuter en mode interactif :
google-lens pro activate
# Ou définir une variable d'environnement :
export LENS_LICENSE_KEY="<votre-clé-de-licence-polar>"

Vérifier le statut de la licence :

google-lens pro status

Désactiver sur cette machine :

google-lens pro deactivate

7. Clé Google AI Studio (Optionnelle, Pour --studio Uniquement)

Google Lens Scraper ne nécessite aucune clé API Gemini pour les recherches standard ou les attributs de produit—ceux-ci sont déduits nativement des métadonnées Lens avec zéro friction.

Pour synthétiser des packshots de studio IA 8K (--studio), configurez votre clé une fois :

google-lens setup-ai --key "<votre-clé-api-gemini>"
# Ou définir une variable d'environnement :
export GEMINI_API_KEY="<votre-clé-api-gemini>"

8. Statut de la session et Authentification Google

Google Lens nécessite une session Google authentifiée pour des correspondances visuelles complètes et pour éviter les limites de débit /sorry/index :

google-lens status

Si non authentifié et exécuté dans un environnement de bureau interactif :

google-lens login

Pour les environnements headless/cloud/CI, transmettez l'état de la session via une variable d'environnement :

export LENS_STORAGE_STATE_JSON="<état-de-stockage-en-base64-ou-json-brut>"

---

Scripts d'aide fournis

Pour les workflows programmatiques et les opérations par lots, utilisez les scripts fournis dans scripts/. Ces scripts incluent les métadonnées de dépendance en ligne PEP 723.

Recherche et Filtrage d'image unique (scripts/search_image.py)

Recherchez une image avec un filtrage intégré par prix, nombre de résultats ou mode :

# Recherche de base avec sortie JSON
python3 scripts/search_image.py "https://exemple.com/photo.jpg" --json

# Filtrer les correspondances visuelles (par ex. max 5 résultats)
python3 scripts/search_image.py "chemin/vers/image.png" --max-results 5 --json

# Extraction OCR rapide
python3 scripts/search_image.py "chemin/vers/reçu.jpg" --ocr-only --json

Traitement par lots d'images (scripts/batch_search.py)

Traitez un répertoire d'images ou une liste d'URL de manière asynchrone :

# Traiter toutes les images d'un répertoire
python3 scripts/batch_search.py --dir ./images/ --output ./resultats_lot.json

# Traiter une liste d'URL depuis un fichier
python3 scripts/batch_search.py --urls-file ./urls_images.txt --output ./resultats_lot.json --concurrency 3

---

Interprétation de la sortie

Lorsque --json-output est utilisé, la charge utile JSON suit cette structure :

{
  "query": "https://exemple.com/article.jpg",
  "ocr_text": "Texte détecté à partir de l'image...",
  "knowledge_graph": {
    "title": "Nom de l'objet / entité identifié",
    "subtitle": "Classification (ex. Chaussure / Plante)",
    "description": "Brève description encyclopédique",
    "website": "https://..."
  },
  "visual_matches": [
    {
      "title": "Titre du produit",
      "link": "https://magasin.com/article",
      "source": "Nom du magasin",
      "price": "99,00 €",
      "thumbnail": "https://..."
    }
  ],
  "detected_objects": [
    {
      "id": "objet_1",
      "bounding_box": {
        "center_x": 0.5,
        "center_y": 0.5,
        "width": 0.3,
        "height": 0.4
      }
    }
  ]
}

---

Dépannage et Bonnes pratiques

1. Contournement de blocage (HTTP 429 / CAPTCHA) : Si les demandes de correspondance visuelle sont limitées en débit, passez en --ocr-only (garantie zéro CAPTCHA) ou authentifiez-vous via google-lens login ou LENS_STORAGE_STATE_JSON.
2. Images locales : Les chemins de fichiers locaux (.png, .jpg, .jpeg, .webp, .bmp, .gif) sont automatiquement téléchargés vers le point de terminaison de téléchargement rapide de Google.
3. Exécution Headless : Les recherches s'exécutent en mode headless par défaut. Dans les environnements de débogage, passez --no-headless pour inspecter le navigateur.

Pour les indicateurs CLI complets, les paramètres de configuration et les schémas JSON détaillés, consultez references/REFERENCE.md.