taazkareem/google-lens-scraper

Google Lens エージェントスキル

このスキルにより、AIエージェントはGoogle Lensを介して、逆画像検索、光学文字認識（OCR）テキスト抽出、ビジュアルエンティティ検出、ショッピングマッチ・価格情報の取得を実行できます。

前提条件とインストール

環境にgoogle-lensがまだインストールされていない場合は、パッケージをインストールし、ステルスChromiumブラウザバイナリをダウンロードします：

pip install google-lens-scraper
patchright install chromium

注記： 高速パスOCRモード（--ocr-only）はPythonパッケージのみが必要で、Chromiumバイナリをダウンロードせずにすぐに動作します。

クイックスタートレシピ

1. 逆画像検索とビジュアルインテリジェンス（デフォルトモード）

一致する商品、Webソース、正規化された価格分析、マルチモーダル属性分析を検索するには：

google-lens search "<image-url-or-path>" --json-output

注：デフォルトでは、google-lens search は、GEMINI_API_KEY が存在する場合、eコマースの価格正規化（--enrich）と深層マルチモーダル属性分析（--analyze）をGemini 3.8 Flashで自動実行します。

エージェントのコンテキスト内フォールバック戦略: results.analysis が null の場合（ホスト環境に GEMINI_API_KEY が設定されていないため）、あなた（AIエージェント） は、自身の会話コンテキスト内でクエリ画像と返された visual_matches を直接検査し、製品属性（ブランド、モデルシルエット、素材、状態、推定価格、真贋の手がかり）を推測する必要があります。これにより、追加のAPIキーを必要とせず、ユーザーにゼロのフリクションを保証します。

2. Nano Banana Pro 8K AI Studioパックショット生成

参照画像から、白い背景の上に超高精細な8K商用カタログパックショットを合成するには：

google-lens search "<image-url-or-path>" --studio --studio-output ./packshot.png

オプションでカスタムプロンプトを指定できます：

google-lens search "<image-url-or-path>" --studio --studio-prompt "黒いブラシ仕上げの花崗岩の上にソフトな劇的なリムライティングを施した8Kスタジオカタログショット"

3. 高速パスOCRと物体検出（1秒未満、CAPTCHAなし）

画像からテキストまたはバウンディングボックスを抽出するには（Chromium Protobufエンドポイントを使用、ブラウザオーバーヘッドなし）：

google-lens search "<image-url-or-path>" --ocr-only --json-output

4. eコマースと転売アービトラージインテリジェンス（Pro）

クリーンな正規URL、正規化された価格範囲（最小/最大/平均）、および最安値の確認済み販売者（「ベストディール」）を特定するには：

google-lens search "<image-url-or-path>" --enrich --json-output

強化されたコマースデータをクリーンなJSONに直接エクスポートするには：

google-lens search "<image-url-or-path>" --export-json deals.json

5. リアルタイムトークンとコスト会計

すべてのGemini API呼び出し（Gemini 3.8 FlashとNano Banana Pro）は、組み込みの gemini-cost-calculator を使用して自動的に追跡されます。CLIまたはSDKから呼び出すと、results.cost は正確なトークン使用量と米ドルでのコストを返します：

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

6. ライセンスアクティベーションとセットアップ（Pro）

Pro機能（市場価格インテリジェンス、クリーンURL、JSONエクスポート、スタジオパック）を使用するには、アクティブなPolar.shライセンスが必要です。

ライセンスの購入（ブラウザ）：

google-lens buy pro
# またはプランを指定：
google-lens buy --plan annual

お使いのブラウザでPolar.shのチェックアウトページが直接開き、プラン（Lifetime、Annual、Monthly）を選択できます。

ターミナルでアクティベート：

google-lens pro activate "<your-polar-license-key>"
# または対話的に実行：
google-lens pro activate
# または環境変数を設定：
export LENS_LICENSE_KEY="<your-polar-license-key>"

ライセンスステータスの確認：

google-lens pro status

このマシンで非アクティブ化：

google-lens pro deactivate

7. Google AI Studioキー（オプション、--studioのみ）

Google Lens Scraperは、通常の検索や製品属性にGemini APIキーを必要としません。これらはLensメタデータからネイティブに推定され、摩擦がゼロです。

8K AIスタジオパックショット（--studio）を合成するには、キーを一度設定します：

google-lens setup-ai --key "<your-gemini-api-key>"
# または環境変数を設定：
export GEMINI_API_KEY="<your-gemini-api-key>"

8. セッションステータスとGoogle認証

Google Lensは、完全なビジュアルマッチと /sorry/index レート制限を回避するために、認証されたGoogleセッションを必要とします：

google-lens status

認証されておらず、インタラクティブなデスクトップ環境で実行している場合：

google-lens login

ヘッドレス/クラウド/CI環境の場合は、環境変数を介してセッション状態を渡します：

export LENS_STORAGE_STATE_JSON="<base64-or-raw-json-storage-state>"

---

バンドルヘルパースクリプト

プログラムによるワークフローとバッチ操作のために、scripts/ ディレクトリにあるバンドルスクリプトを使用します。これらのスクリプトには、PEP 723 のインラインディペンデンシーメタデータが含まれています。

単一画像の検索とフィルタリング（scripts/search_image.py）

価格、結果数、モードによる組み込みフィルタリングを使用して画像を検索します：

# JSON出力による基本的な検索
python3 scripts/search_image.py "https://example.com/photo.jpg" --json

# ビジュアルマッチのフィルタリング（例：最大5件の結果）
python3 scripts/search_image.py "path/to/image.png" --max-results 5 --json

# 高速OCR抽出
python3 scripts/search_image.py "path/to/receipt.jpg" --ocr-only --json

バッチ画像処理（scripts/batch_search.py）

画像ディレクトリまたはURLのリストを非同期で処理します：

# ディレクトリ内のすべての画像を処理
python3 scripts/batch_search.py --dir ./images/ --output ./batch_results.json

# ファイルからのURLリストを処理
python3 scripts/batch_search.py --urls-file ./image_urls.txt --output ./batch_results.json --concurrency 3

---

出力の解釈

--json-output を使用する場合、JSONペイロードは次の構造に従います：

{
  "query": "https://example.com/item.jpg",
  "ocr_text": "画像から検出されたテキスト...",
  "knowledge_graph": {
    "title": "識別されたオブジェクト/エンティティ名",
    "subtitle": "分類（例：フットウェア/植物）",
    "description": "簡潔な百科事典的な説明",
    "website": "https://..."
  },
  "visual_matches": [
    {
      "title": "商品タイトル",
      "link": "https://store.com/item",
      "source": "ストア名",
      "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
      }
    }
  ]
}

---

トラブルシューティングとベストプラクティス

1. Bot対策（HTTP 429 / CAPTCHA）：ビジュアルマッチリクエストがレート制限された場合は、--ocr-only（CAPTCHAが発生しないことが保証されています）に切り替えるか、google-lens login または LENS_STORAGE_STATE_JSON で認証します。
2. ローカル画像：ローカルファイルパス（.png、.jpg、.jpeg、.webp、.bmp、.gif）は、Googleの高速アップロードエンドポイントに自動的にアップロードされます。
3. ヘッドレス実行：検索はデフォルトでヘッドレスで実行されます。デバッグ環境では、--no-headless を渡してブラウザを検査します。

完全なCLIフラグ、設定パラメータ、詳細なJSONスキーマについては、references/REFERENCE.md を参照してください。