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:
| Leg | What | When it runs |
|---|---|---|
| vision | Google Cloud Vision web_detection — the always-on official baseline: entities, pages with matching images, full/partial matches, visually similar images | Always (needs GOOGLE_CLOUD_VISION_API_KEY) |
| image_search_mcp | Contabo 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 engine | URL inputs only; needs IMAGE_SEARCH_MCP_TOKEN |
| scrappa | Scrappa Google Lens API (GET https://scrappa.co/api/google/lens, verified) | Only if SCRAPPA_API_KEY is set; URL inputs only (no upload) |
| trace | Trace web face search (async POST /v1/scans → poll → POST /reveal), $0.50/search | Only if TRACE_API_KEY is set and --face-search is passed — never silently |
| local | Contabo SigLIP 2 image search + DeepFace face search over the user's own collection | Only with --collection <path-or-name> |
| followup | PimEyes 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
| Flag | Description |
|---|---|
--image | Path to a local image file |
--url | URL of an image to search (mutually exclusive with --image) |
input | Positional image path or URL (convenience; same as above) |
--face-search | Run Trace web face search. Required for any Trace call — the skill never face-searches the web without it |
--pimeyes-domains | PimEyes 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 |
--collection | Local collection path or name; enables the Contabo SigLIP 2 + DeepFace legs |
--legs | Comma-separated legs: vision,mcp,scrappa,trace,local,followup (default: all) |
--timeout | Per-request timeout in seconds (default: 30; Scrappa gets at least 45s) |
--max-results | Max results kept per engine / per bucket (default: 20) |
--output | Also write the JSON report to this file (stdout always gets it) |
--allow-trace-over-cap | Allow a Trace search past the 8/month cap |
--trace-state-file | Trace usage state file (default: ~/.reverse-image-search/trace_usage.json) |
Environment
| Variable | Required? | Purpose |
|---|---|---|
GOOGLE_CLOUD_VISION_API_KEY | Yes (baseline) | GCP Vision API key, sent as X-Goog-Api-Key |
IMAGE_SEARCH_MCP_URL | No | Base 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_TOKEN | Yes for MCP leg | Bearer token for the MCP service (value only on Contabo at /root/hermes-ops/secrets/image-search-mcp-token) |
REVIMG_TOKEN | Yes for local + follow-up legs | Bearer token for the Contabo SigLIP 2 / DeepFace / follow-up services (value only on Contabo at /root/hermes-ops/secrets/revimg-token) |
LOCAL_IMAGE_SEARCH_URL | No | Contabo SigLIP 2 search endpoint (default https://revimg-siglip.194.233.74.33.sslip.io — VERIFIED live 2026-11-15) |
LOCAL_FACE_SEARCH_URL | No | Contabo DeepFace search endpoint (default https://revimg-faces.194.233.74.33.sslip.io — VERIFIED live 2026-11-15) |
DOMAIN_FOLLOWUP_URL | No | Contabo 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_KEY | No | Scrappa Lens API key; leg skipped silently when absent |
TRACE_API_KEY | No | Trace face-search API key; leg skipped silently when absent |
SCRAPPA_API_BASE | No | Override Scrappa host (default https://scrappa.co — VERIFIED 2026-11-15; api.scrappa.co times out, do not use) |
TRACE_API_BASE | No | Override Trace host (default https://api.traceaifacescan.app — VERIFY) |
REVERSE_IMAGE_SEARCH_TRACE_STATE_FILE | No | Override 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":
- 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. - SECONDARY — TinEye domain filter: official TinEye feature (web UI
field / API
domain=param), but currentlynot_supportedin 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. - SECONDARY — Vision + client-side domain filter: filters this run's
Vision
web_detectionURLs 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-capoverrides 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 ranlegs— per-leg results withstatusanddetail; the MCP leg also carries per-engine statuses (BaiDu,Tineye,Yandex)matched_pages— deduplicated pages carrying the image (or a match), each withengines(which legs found it) andvision_corroboratedvisually_similar— deduplicated visually similar imagesentities— Vision web entities (descriptions + scores)best_guess_labels— Vision best-guess labelsface_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 spendsummary— 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.mdTODO. Until then those legs reportnot_configuredand 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.