Community연구 & 데이터 분석github.com

reverse-image-search

Combined reverse image search + face search. Given a local image file or an image URL, fans out to Google Cloud Vision web_detection (always-on baseline), the Contabo Image_Search_Mcp service (BaiDu / Tineye / Yandex — verified live 2026-11-15; Lens/Bing return 0), Scrappa Lens (URL-only, key optional), Trace web face search (paid, explicit --face-search only), Contabo local SigLIP 2 + DeepFace collection search, and a PimEyes domain follow-up leg driven only by manually pasted-back domains (PimEyes itself is never queried), then merges everything into one deduplicated JSON report with per-engine status and Vision cross-validation.

reverse-image-search란 무엇인가요?

reverse-image-search is a Claude Code agent skill that combined reverse image search + face search. Given a local image file or an image URL, fans out to Google Cloud Vision web_detection (always-on baseline), the Contabo Image_Search_Mcp service (BaiDu / Tineye / Yandex — verified live 2026-11-15; Lens/Bing return 0), Scrappa Lens (URL-only, key optional), Trace web face search (paid, explicit --face-search only), Contabo local SigLIP 2 + DeepFace collection search, and a PimEyes domain follow-up leg driven only by manually pasted-back domains (PimEyes itself is never queried), then merges everything into one deduplicated JSON report with per-engine status and Vision cross-validation.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BoredSexyJordan/reverse-image-search-skill/tree/HEAD

Installed? Explore more 연구 & 데이터 분석 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Reverse Image Search + Face Search

One combined skill for "where is this image from?" and "where else does this face appear?" — web reverse search and face search in a single run, with a single merged report.

When to Use

  • "reverse image search", "find this image online", "where is this photo from"
  • "search this picture", "find the source of this image", "is this image used elsewhere"
  • "find this face", "where else does this person appear", "face search this photo"
  • "is this photo in our collection" (local search, with --collection)

How It Works

reverse_image_search.py (Python stdlib only — no pip installs, no requests needed) fans out in parallel daemon threads to up to five legs:

LegWhatWhen it runs
visionGoogle Cloud Vision web_detection — the always-on official baseline: entities, pages with matching images, full/partial matches, visually similar imagesAlways (needs GOOGLE_CLOUD_VISION_API_KEY)
image_search_mcpContabo Image_Search_Mcp service (PicImageSearch wrapper) over MCP SSE transport: BaiDu, Tineye, Yandex (verified live 2026-11-15; Lens/Bing return 0), best-effort per engineURL inputs only; needs IMAGE_SEARCH_MCP_TOKEN
scrappaScrappa Google Lens API (GET https://scrappa.co/api/google/lens, verified)Only if SCRAPPA_API_KEY is set; URL inputs only (no upload)
traceTrace web face search (async POST /v1/scans → poll → POST /reveal), $0.50/searchOnly if TRACE_API_KEY is set and --face-search is passed — never silently
localContabo SigLIP 2 image search + DeepFace face search over the user's own collectionOnly with --collection <path-or-name>
followupPimEyes domain follow-up (see below): Contabo crawl + face match (primary), TinEye domain filter (secondary, currently not_supported via MCP), Vision + client-side domain filter (secondary)Only with --pimeyes-domains (manually pasted-back domains)

Every leg reports a status: ok / empty / error / degraded / skipped / not_configured. A dead engine shows as degraded or error — never as "no results". empty means the engine genuinely searched and found nothing. Exit code is 0 whenever a report is produced, even if some legs failed.

Cross-validation (poisoned-SERP risk): since Sep 2026 Google SERPs can be poisoned, so any Lens/SERP-wrapper match is suspect on its own. Every merged match is flagged vision_corroborated: true when the same URL also appears in Vision web_detection results. For anything that matters, trust corroborated matches first and treat uncorroborated wrapper-only hits as leads, not proof.

Usage

# Local file (Vision baseline + local legs if --collection is given;
# URL-only legs are skipped cleanly, not failed)
python3 reverse_image_search.py --image /path/to/photo.jpg

# Image URL (all legs eligible)
python3 reverse_image_search.py --url "https://example.com/photo.jpg"

# Positional path/URL, or one line on stdin, also work
python3 reverse_image_search.py /path/to/photo.jpg
echo /path/to/photo.jpg | python3 reverse_image_search.py

# Explicit face search (Trace, $0.50/search, capped at 8/month)
python3 reverse_image_search.py --url "https://example.com/face.jpg" --face-search

# Search the user's own collection too (Contabo SigLIP 2 + DeepFace)
python3 reverse_image_search.py --image ./photo.jpg --collection photos --face-search

# PimEyes paste-back: a human ran the free PimEyes search and pasted the
# domains + scores; the skill runs the domain follow-up (never PimEyes itself)
python3 reverse_image_search.py --image ./face.jpg --face-search \
  --pimeyes-domains '[{"domain": "example.com", "score": 87}]'
python3 reverse_image_search.py --image ./face.jpg --face-search \
  --pimeyes-domains ./pimeyes-domains.json

# Fewer legs, or write the report to a file as well as stdout
python3 reverse_image_search.py --url <url> --legs vision,mcp
python3 reverse_image_search.py --image ./photo.jpg --output report.json

Arguments

FlagDescription
--imagePath to a local image file
--urlURL of an image to search (mutually exclusive with --image)
inputPositional image path or URL (convenience; same as above)
--face-searchRun Trace web face search. Required for any Trace call — the skill never face-searches the web without it
--pimeyes-domainsPimEyes manual paste-back: JSON list of {"domain", "score"} (or a path to a JSON file holding one) from a human-run PimEyes free search. Triggers the domain follow-up leg. Also accepts {"domain": score} objects and bare domain strings
--collectionLocal collection path or name; enables the Contabo SigLIP 2 + DeepFace legs
--legsComma-separated legs: vision,mcp,scrappa,trace,local,followup (default: all)
--timeoutPer-request timeout in seconds (default: 30; Scrappa gets at least 45s)
--max-resultsMax results kept per engine / per bucket (default: 20)
--outputAlso write the JSON report to this file (stdout always gets it)
--allow-trace-over-capAllow a Trace search past the 8/month cap
--trace-state-fileTrace usage state file (default: ~/.reverse-image-search/trace_usage.json)

Environment

VariableRequired?Purpose
GOOGLE_CLOUD_VISION_API_KEYYes (baseline)GCP Vision API key, sent as X-Goog-Api-Key
IMAGE_SEARCH_MCP_URLNoBase URL of the Contabo Image_Search_Mcp service (default https://imagesearch-private.194.233.74.33.sslip.io — VERIFIED live 2026-11-15)
IMAGE_SEARCH_MCP_TOKENYes for MCP legBearer token for the MCP service (value only on Contabo at /root/hermes-ops/secrets/image-search-mcp-token)
REVIMG_TOKENYes for local + follow-up legsBearer token for the Contabo SigLIP 2 / DeepFace / follow-up services (value only on Contabo at /root/hermes-ops/secrets/revimg-token)
LOCAL_IMAGE_SEARCH_URLNoContabo SigLIP 2 search endpoint (default https://revimg-siglip.194.233.74.33.sslip.io — VERIFIED live 2026-11-15)
LOCAL_FACE_SEARCH_URLNoContabo DeepFace search endpoint (default https://revimg-faces.194.233.74.33.sslip.io — VERIFIED live 2026-11-15)
DOMAIN_FOLLOWUP_URLNoContabo domain-follow-up endpoint for the PimEyes leg: crawl a domain + local face match (default https://revimg-faces.194.233.74.33.sslip.io/followup/json — VERIFIED live 2026-11-15)
SCRAPPA_API_KEYNoScrappa Lens API key; leg skipped silently when absent
TRACE_API_KEYNoTrace face-search API key; leg skipped silently when absent
SCRAPPA_API_BASENoOverride Scrappa host (default https://scrappa.co — VERIFIED 2026-11-15; api.scrappa.co times out, do not use)
TRACE_API_BASENoOverride Trace host (default https://api.traceaifacescan.app — VERIFY)
REVERSE_IMAGE_SEARCH_TRACE_STATE_FILENoOverride the Trace usage state file path

See README.md for the full env reference, the budget model, and the TODO list (TBD endpoints + VERIFY flags).

PimEyes Manual Paste-Back (the domain follow-up leg)

PimEyes has no self-serve API and its free tier cannot be automated reliably (CAPTCHA blocks unattended automation; PimEyes explicitly bans automation/scraping — warn/suspend/ban per their 2025-09-23 letter; free results are also rate-limited). So the skill never touches PimEyes: no querying pimeyes.com, no scraping, no unofficial tools, no browser automation.

What the skill does instead: a human (Jordan, or Anna in a logged-in browser session) runs the free PimEyes search manually. Free result cards show the site/domain name and a similarity score per result, even though full URLs are hidden. The human pastes those domains + scores back via --pimeyes-domains (JSON string or JSON file), and the skill runs the automated follow-up — "given a domain, find the matching image":

  1. PRIMARY — Contabo crawl + face match (DOMAIN_FOLLOWUP_URL, worker B is building it): fetch the domain's pages, extract images, run a local face match against the query face. The only mechanism that finds ANY photo of the face on the domain, not just copies of the query photo.
  2. SECONDARY — TinEye domain filter: official TinEye feature (web UI field / API domain= param), but currently not_supported in the skill — the Image_Search_Mcp Tineye contract exposes no domain param (verified in the server source). Exact-photo match only. See README TODO-7.
  3. SECONDARY — Vision + client-side domain filter: filters this run's Vision web_detection URLs by domain in code (Vision has no server-side domain parameter). No extra API call. Only returns what Google indexed.

Lens has NO domain filter and is never used for this leg. Follow-up results merge into the same report, per domain, with per-mechanism status (same degraded-not-absent rule as other engines). Contabo/TinEye matches also fold into matched_pages with followup:contabo / followup:tineye engine tags; Vision-domain matches get a followup:vision tag on their existing entries.

Terms note: PimEyes restricts use to self-search — this leg is for Jordan's own face / faces he has a legitimate reason to search, not a general third-party lookup tool. PimEyes paid access stays manual and occasional (a one-month Open Plus burst when a batch of high-value faces justifies it, or a $14.99 unlock for a single critical search — each needs Jordan's explicit yes) and is NOT part of the skill. Trace + FaceCheck.ID + Yandex remain the automated face legs.

Binding Gates (Jordan's, never violated)

  • Budget: MAX $5/month, free tiers first. Vision (1,000/mo free) and the free scraping engines carry the load. Trace is the only per-search spend: hard cap 8 Trace searches/month ($4.00), counted in ~/.reverse-image-search/trace_usage.json (month-keyed, counted at the reveal — the billed step). At the cap the leg skips itself and says so in the report; only an explicit --allow-trace-over-cap overrides it.
  • Never call a paid API when its key is absent. The skill works fully with Scrappa/Trace keys unset (Vision free tier + free engines only).
  • Face search is explicit or it doesn't happen. Trace runs only with --face-search. No silent web face lookups, ever.
  • PimEyes is never automated. No querying, scraping, unofficial tools, or browser automation against PimEyes — manual paste-back only (see above). This protects Jordan's legitimate account from a ban.
  • Face data is biometric data. Trace's ToS bans background checks, hiring, lending, insurance, surveillance, law enforcement, and minors. A match is a lead, not an identity — verify against the source page and corroborate. For sensitive subjects prefer the local DeepFace leg (nothing leaves the VPS).
  • No secrets in files or output. Keys come from the environment only. The report never contains a key. Never paste a key into a file, a log, or chat.

Output

One structured JSON report on stdout (logs go to stderr, stdout is pure JSON):

  • query / query_type — the image source (file path or URL)
  • timestamp — when the search ran
  • legs — per-leg results with status and detail; the MCP leg also carries per-engine statuses (BaiDu, Tineye, Yandex)
  • matched_pages — deduplicated pages carrying the image (or a match), each with engines (which legs found it) and vision_corroborated
  • visually_similar — deduplicated visually similar images
  • entities — Vision web entities (descriptions + scores)
  • best_guess_labels — Vision best-guess labels
  • face_matches — Trace + local DeepFace face matches (platform, handle, score, source URL)
  • domain_followup — per-domain PimEyes follow-up results (pasted score, per-mechanism status + matches)
  • budget.trace — Trace searches used this month, cap, estimated spend
  • summary — counts, corroborated-page count, per-leg status table

Known Limitations

  • Image_Search_Mcp in HTTP/SSE mode is URL-only — it has no upload endpoint, so local files skip that leg (Vision still covers them). Same for Scrappa (URL-only by design).
  • Yandex is rate-limit sensitive: the MCP leg spaces engine calls 2s apart. Don't parallelize per-engine calls inside that leg.
  • The Contabo endpoint URLs and the Trace base URL are placeholders/guesses until workers A/B land and the APIs are verified against live docs — see README.md TODO. Until then those legs report not_configured and the skill still delivers a full Vision-based report.
  • The TinEye domain-filter secondary is not_supported: the MCP server's Tineye contract has no domain param. The follow-up leg still works via the Contabo primary + Vision secondary.
  • Trace forwards roughly half of thin-result searches to a commercial face-search service (per its own docs via an independent comparison) — a second party may see query crops.

관련 스킬