taazkareem/google-lens-scraper

Habilidade do Agente Google Lens

Esta habilidade permite que um agente de IA execute buscas reversas por imagem, extraia texto por reconhecimento óptico de caracteres (OCR), detecte entidades visuais e encontre correspondências de compra/preços via Google Lens.

Pré-requisitos e Instalação

Se o pacote google-lens ainda não estiver instalado no ambiente, instale o pacote e faça o download do navegador Chromium stealth:

pip install google-lens-scraper
patchright install chromium

Nota: O modo rápido de OCR (--ocr-only) requer apenas o pacote Python e funciona imediatamente, sem necessidade de baixar os binários do Chromium.

Receitas de Início Rápido

1. Busca Reversa por Imagem e Inteligência Visual (Modo Padrão)

Para encontrar produtos correspondentes, fontes web, análises de preços normalizadas e análise multimodal de atributos:

google-lens search "<url-ou-caminho-da-imagem>" --json-output

Nota: Por padrão, google-lens search executa automaticamente a normalização de preços de e-commerce (--enrich) e a análise profunda multimodal de atributos (--analyze) via Gemini 3.8 Flash, se a variável GEMINI_API_KEY estiver presente.

Estratégia de Fallback no Contexto do Agente: Se results.analysis for null (porque GEMINI_API_KEY não está configurada no ambiente hospedeiro), você (o Agente de IA) deve inspecionar a imagem da consulta e as visual_matches retornadas diretamente no seu próprio contexto de conversa para deduzir os atributos do produto (marca, silhueta do modelo, materiais, condição, MSRP estimado, indícios de autenticidade). Isso garante zero atrito para usuários sem exigir chaves de API adicionais.

2. Geração de Packshot de Estúdio Nano Banana Pro 8K AI

Para sintetizar um packshot de catálogo comercial ultra-nítido em 8K sobre um fundo branco imaculado a partir de uma imagem de referência:

google-lens search "<url-ou-caminho-da-imagem>" --studio --studio-output ./packshot.png

Você pode opcionalmente fornecer um prompt personalizado:

google-lens search "<url-ou-caminho-da-imagem>" --studio --studio-prompt "Fotografia de catálogo em estúdio 8K sobre granito preço escovado com iluminação dramática suave de borda"

3. OCR de Caminho Rápido e Detecção de Objetos (Subssegundo, Sem CAPTCHA)

Para extrair texto ou caixas delimitadoras de uma imagem (usa o endpoint Protobuf do Chromium, sem sobrecarga do navegador):

google-lens search "<url-ou-caminho-da-imagem>" --ocr-only --json-output

4. Inteligência de E-Commerce e Arbitragem de Revenda (Pro)

Para resolver URLs canônicas limpas, faixas de preço normalizadas (mín/máx/média) e identificar o vendedor verificado com menor preço ("Melhor Oferta"):

google-lens search "<url-ou-caminho-da-imagem>" --enrich --json-output

Para exportar dados comerciais enriquecidos diretamente para JSON limpo:

google-lens search "<url-ou-caminho-da-imagem>" --export-json deals.json

5. Contabilidade de Tokens e Custos em Tempo Real

Cada invocação da API Gemini (Gemini 3.8 Flash e Nano Banana Pro) é rastreada automaticamente usando o gemini-cost-calculator integrado. Ao chamar via CLI ou SDK, results.cost retorna o uso exato de tokens e o custo financeiro em USD:

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

6. Ativação e Configuração de Licença (Pro)

Os recursos Pro (inteligência de preços de mercado, URLs limpas, exportação JSON, pacotes de estúdio) exigem uma licença ativa do Polar.sh.

Comprar uma Licença (Navegador):

google-lens buy pro
# Ou especifique um plano:
google-lens buy --plan annual

Abre a página de checkout do Polar.sh diretamente no seu navegador para escolher um plano (Vitalício, Anual ou Mensal).

Ativar no Terminal:

google-lens pro activate "<sua-chave-de-licenca-polar>"
# Ou execute interativamente:
google-lens pro activate
# Ou defina a variável de ambiente:
export LENS_LICENSE_KEY="<sua-chave-de-licenca-polar>"

Verificar Status da Licença:

google-lens pro status

Desativar nesta Máquina:

google-lens pro deactivate

7. Chave do Google AI Studio (Opcional, Apenas para --studio)

O Google Lens Scraper não requer nenhuma chave da API Gemini para buscas regulares ou atributos de produto — estes são deduzidos nativamente dos metadados do Lens com zero atrito.

Para sintetizar packshots de estúdio 8K AI (--studio), configure sua chave uma vez:

google-lens setup-ai --key "<sua-chave-da-api-gemini>"
# Ou defina a variável de ambiente:
export GEMINI_API_KEY="<sua-chave-da-api-gemini>"

8. Status da Sessão e Autenticação Google

O Google Lens requer uma sessão autenticada do Google para correspondências visuais completas e para evitar limites de taxa /sorry/index:

google-lens status

Se não autenticado e executando em um ambiente de desktop interativo:

google-lens login

Para ambientes headless/nuvem/CI, passe o estado da sessão via variável de ambiente:

export LENS_STORAGE_STATE_JSON="<estado-de-armazenamento-json-base64-ou-raw>"

---

Scripts Auxiliares Empacotados

Para fluxos de trabalho programáticos e operações em lote, use os scripts empacotados localizados em scripts/. Estes scripts incluem metadados de dependência inline conforme PEP 723.

Busca de Imagem Única e Filtragem (scripts/search_image.py)

Busque uma imagem com filtragem integrada por preço, contagem de resultados ou modo:

# Busca básica com saída JSON
python3 scripts/search_image.py "https://exemplo.com/foto.jpg" --json

# Filtrar correspondências visuais (ex.: máximo 5 resultados)
python3 scripts/search_image.py "caminho/para/imagem.png" --max-results 5 --json

# Extração rápida de OCR
python3 scripts/search_image.py "caminho/para/recibo.jpg" --ocr-only --json

Processamento em Lote de Imagens (scripts/batch_search.py)

Processe um diretório de imagens ou uma lista de URLs de forma assíncrona:

# Processar todas as imagens em um diretório
python3 scripts/batch_search.py --dir ./imagens/ --output ./resultados_lote.json

# Processar lista de URLs a partir de arquivo
python3 scripts/batch_search.py --urls-file ./urls_imagens.txt --output ./resultados_lote.json --concurrency 3

---

Interpretando a Saída

Quando --json-output é usado, o payload JSON segue esta estrutura:

{
  "query": "https://exemplo.com/item.jpg",
  "ocr_text": "Texto detectado da imagem...",
  "knowledge_graph": {
    "title": "Nome do Objeto/Entidade Identificada",
    "subtitle": "Classificação (ex.: Calçados / Planta)",
    "description": "Breve descrição enciclopédica",
    "website": "https://..."
  },
  "visual_matches": [
    {
      "title": "Título do Produto",
      "link": "https://loja.com/item",
      "source": "Nome da Loja",
      "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
      }
    }
  ]
}

---

Solução de Problemas e Melhores Práticas

1. Bloqueio de Bot (HTTP 429 / CAPTCHA): Se as solicitações de correspondência visual estiverem com limite de taxa, mude para --ocr-only (garantia de zero CAPTCHAs) ou autentique-se via google-lens login ou LENS_STORAGE_STATE_JSON.
2. Imagens Locais: Caminhos de arquivos locais (.png, .jpg, .jpeg, .webp, .bmp, .gif) são automaticamente enviados para o endpoint de upload rápido do Google.
3. Execução Headless: As buscas são executadas em modo headless por padrão. Em ambientes de depuração, use --no-headless para inspecionar o navegador.

Para flags completas da CLI, parâmetros de configuração e esquemas JSON detalhados, veja references/REFERENCE.md.