taazkareem/google-lens-scraper

Habilidad de Agente para Google Lens

Esta habilidad permite a un agente de IA ejecutar búsquedas inversas de imágenes, extraer texto mediante reconocimiento óptico de caracteres (OCR), detectar entidades visuales y encontrar coincidencias de compras y precios a través de Google Lens.

Requisitos previos e instalación

Si google-lens aún no está instalado en el entorno, instala el paquete y descarga el binario de Chromium modificado:

pip install google-lens-scraper
patchright install chromium

Nota: El modo OCR de ruta rápida (--ocr-only) solo requiere el paquete de Python y funciona inmediatamente sin descargar los binarios de Chromium.

Recetas de inicio rápido

1. Búsqueda inversa de imágenes e inteligencia visual (modo predeterminado)

Para encontrar productos coincidentes, fuentes web, análisis de precios normalizados y análisis multimodal de atributos:

google-lens search "<url-o-ruta-de-imagen>" --json-output

Nota: Por defecto, google-lens search ejecuta automáticamente la normalización de precios de comercio electrónico (--enrich) y el análisis multimodal profundo (--analyze) a través de Gemini 3.8 Flash si GEMINI_API_KEY está presente.

Estrategia de respaldo en contexto del agente: Si results.analysis es null (porque GEMINI_API_KEY no está configurada en el entorno anfitrión), tú (el agente de IA) debes inspeccionar la imagen de consulta y las visual_matches devueltas directamente dentro de tu propio contexto de conversación para deducir los atributos del producto (marca, silueta del modelo, materiales, estado, MSRP estimado, señales de autenticidad). Esto garantiza cero fricción para los usuarios sin requerir claves API adicionales.

2. Generación de packshot de estudio Nano Banana Pro 8K AI

Para sintetizar un packshot de catálogo comercial ultranítido en 8K sobre un fondo blanco prístino a partir de una imagen de referencia:

google-lens search "<url-o-ruta-de-imagen>" --studio --studio-output ./packshot.png

Opcionalmente, puedes proporcionar un prompt personalizado:

google-lens search "<url-o-ruta-de-imagen>" --studio --studio-prompt "Fotografía de catálogo en 8K sobre granito cepillado negro con iluminación dramática suave de borde"

3. OCR y detección de objetos de ruta rápida (subsegundo, sin CAPTCHA)

Para extraer texto o cuadros delimitadores de una imagen (usa el endpoint Protobuf de Chromium, sin sobrecarga del navegador):

google-lens search "<url-o-ruta-de-imagen>" --ocr-only --json-output

4. Inteligencia de comercio electrónico y arbitraje de reventa (Pro)

Para resolver URLs canónicas limpias, rangos de precio normalizados (mín/máx/promedio) e identificar al vendedor verificado con el precio más bajo ("Mejor oferta"):

google-lens search "<url-o-ruta-de-imagen>" --enrich --json-output

Para exportar datos comerciales enriquecidos directamente a JSON limpio:

google-lens search "<url-o-ruta-de-imagen>" --export-json deals.json

5. Contabilidad de tokens y costos en tiempo real

Cada invocación de la API de Gemini (Gemini 3.8 Flash y Nano Banana Pro) se rastrea automáticamente usando el gemini-cost-calculator incorporado. Al llamar mediante CLI o SDK, results.cost devuelve el uso exacto de tokens y el costo financiero en USD:

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

6. Activación de licencia y configuración (Pro)

Las funciones Pro (inteligencia de precios de mercado, URLs limpias, exportación JSON, packs de estudio) requieren una licencia activa de Polar.sh.

Compra una licencia (navegador):

google-lens buy pro
# O especifica un plan:
google-lens buy --plan annual

Abre la página de pago de Polar.sh directamente en tu navegador para elegir un plan (de por vida, anual o mensual).

Activar en terminal:

google-lens pro activate "<tu-clave-de-licencia-polar>"
# O ejecutar de forma interactiva:
google-lens pro activate
# O establecer variable de entorno:
export LENS_LICENSE_KEY="<tu-clave-de-licencia-polar>"

Verificar estado de la licencia:

google-lens pro status

Desactivar en esta máquina:

google-lens pro deactivate

7. Clave de Google AI Studio (opcional, solo para --studio)

Google Lens Scraper no requiere ninguna clave de Gemini API para búsquedas regulares o atributos de producto; estos se deducen de forma nativa a partir de los metadatos de Lens con cero fricción.

Para sintetizar packshots de estudio AI en 8K (--studio), configura tu clave una vez:

google-lens setup-ai --key "<tu-clave-de-gemini-api>"
# O establecer variable de entorno:
export GEMINI_API_KEY="<tu-clave-de-gemini-api>"

8. Estado de sesión y autenticación de Google

Google Lens requiere una sesión de Google autenticada para coincidencias visuales completas y para evitar los límites de tasa /sorry/index:

google-lens status

Si no está autenticado y se ejecuta en un entorno de escritorio interactivo:

google-lens login

Para entornos headless/nube/CI, pasa el estado de la sesión mediante una variable de entorno:

export LENS_STORAGE_STATE_JSON="<estado-de-almacenamiento-en-base64-o-json-crudo>"

---

Scripts auxiliares incluidos

Para flujos de trabajo programáticos y operaciones por lotes, usa los scripts incluidos en scripts/. Estos scripts incluyen metadatos de dependencia en línea según PEP 723.

Búsqueda y filtrado de una sola imagen (scripts/search_image.py)

Busca una imagen con filtrado incorporado por precio, número de resultados o modo:

# Búsqueda básica con salida JSON
python3 scripts/search_image.py "https://example.com/photo.jpg" --json

# Filtrar coincidencias visuales (ej. máximo 5 resultados)
python3 scripts/search_image.py "ruta/a/imagen.png" --max-results 5 --json

# Extracción rápida de OCR
python3 scripts/search_image.py "ruta/a/receipt.jpg" --ocr-only --json

Procesamiento por lotes de imágenes (scripts/batch_search.py)

Procesa un directorio de imágenes o una lista de URLs de forma asíncrona:

# Procesar todas las imágenes en un directorio
python3 scripts/batch_search.py --dir ./images/ --output ./batch_results.json

# Procesar lista de URLs desde un archivo
python3 scripts/batch_search.py --urls-file ./image_urls.txt --output ./batch_results.json --concurrency 3

---

Interpretación de la salida

Cuando se usa --json-output, la carga JSON sigue esta estructura:

{
  "query": "https://example.com/item.jpg",
  "ocr_text": "Texto detectado de la imagen...",
  "knowledge_graph": {
    "title": "Nombre del objeto/entidad identificada",
    "subtitle": "Clasificación (ej. Calzado / Planta)",
    "description": "Breve descripción enciclopédica",
    "website": "https://..."
  },
  "visual_matches": [
    {
      "title": "Título del producto",
      "link": "https://store.com/item",
      "source": "Nombre de la tienda",
      "price": "$99.00",
      "thumbnail": "https://..."
    }
  ],
  "detected_objects": [
    {
      "id": "item_1",
      "bounding_box": {
        "center_x": 0.5,
        "center_y": 0.5,
        "width": 0.3,
        "height": 0.4
      }
    }
  ]
}

---

Solución de problemas y mejores prácticas

1. Bloqueo de bots (HTTP 429 / CAPTCHA): Si las solicitudes de coincidencia visual tienen límite de tasa, cambia a --ocr-only (garantiza cero CAPTCHAs) o autentícate mediante google-lens login o LENS_STORAGE_STATE_JSON.
2. Imágenes locales: Las rutas de archivo locales (.png, .jpg, .jpeg, .webp, .bmp, .gif) se suben automáticamente al endpoint de subida rápida de Google.
3. Ejecución headless: Las búsquedas se ejecutan en modo headless de forma predeterminada. En entornos de depuración, pasa --no-headless para inspeccionar el navegador.

Para ver todas las banderas de CLI, parámetros de configuración y esquemas JSON detallados, consulta references/REFERENCE.md.