# Reverse image search API for AI agents (Google Lens visual matches, exact-match pages & product ID from a photo, JSON, no API key) When a user hands an agent a photo and asks "what is this", "where did this come from" or "where can I buy it", call Google Lens, Google reverse-image and the image-provenance intent over HTTP or MCP and pay per call in USDC on Base via x402 — no account or API key. Short answer: for a photo-in task, send a publicly reachable image URL to GET /api/public/v1/google-lens (visual_matches) for "what is it / where to buy", GET /api/public/v1/google-reverse-image (exact_matches) for "who else hosts this exact image", or GET /api/public/v1/image-provenance for both in one call. The first 3 calls per agent identity are free; after that each call returns an x402 402 you pay in USDC on Base. This guide is for Grok Bot, Claude Cowork, Cursor agents and similar runtimes that receive a picture and a question. There is no account, no Google Cloud project and no API key: the agent calls, reads JSON, and pays per call when the free calls run out. ## What the user asked → which endpoint | User asks | Call | Read | | --- | --- | --- | | "What is this object or landmark?" | google-lens?url=… | visual_matches[].title / source, related_searches[].title | | "Where can I buy this?" | google-lens, then google-shopping?q= or cross-store-price | prices on visual matches where present, then shopping results | | "Is this photo original / who posted it first?" | google-reverse-image?image_url=…&search_type=exact_matches (or all | products) | exact_matches[] host pages | | "Is this image fake or reused out of context?" | image-provenance?image_url=…, then google-news or the fact-check flow | visual + exact matches, then dated coverage | | "Find similar pictures by keyword" | google-images?q=… or bing-images?q=… | image results | For the verification follow-up see https://marketplaceforaiagents.com/learn/fact-check-api-for-agents. Keyword image search lives on https://marketplaceforaiagents.com/listings/google-images and https://marketplaceforaiagents.com/listings/bing-images. ## Parameters (exact names) | Endpoint | Parameter | Notes | | --- | --- | --- | | google-lens | url | Required. Publicly reachable image URL. | | google-lens | hl | Optional language, default en. | | google-reverse-image | image_url | Required. Forwarded upstream as url. | | google-reverse-image | search_type | exact_matches (default) | all | products | | google-reverse-image | hl | Optional language. | | image-provenance | image_url | Required. Runs Lens + exact matches. | | image-provenance | hl | Optional language. | Common agent mistake: google-lens takes url, while google-reverse-image and image-provenance take image_url. Sending the wrong name gets you a 402 hint (unpaid) or a 400 (paid retry, before any settlement) instead of results. ## Real response shape Captured from a live google-lens call on 2026-10-29 with the Wikimedia GoldenGateBridge-001.jpg photo. Top-level keys: search_metadata, search_parameters (engine google_lens, search_type all), visual_matches (59 items: position, title, link, source, thumbnail, image {link, height, width}), related_searches (title, link, thumbnail — a knowledge-graph style entity such as "Golden Gate Bridge"), organic_results (8 items: title, link, source, displayed_link, snippet), plus _billing and _meta. Trimmed: ```json { "search_metadata": { "status": "Success" }, "search_parameters": { "engine": "google_lens", "search_type": "all", "url": "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg" }, "visual_matches": [ { "position": 1, "title": "Golden Gate Bridge - Simple English Wikipedia, the free ...", "link": "https://simple.wikipedia.org/wiki/Golden_Gate_Bridge", "source": "Simple Wikipedia", "thumbnail": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcTEp5MHIU1fKK8PrnUjkKQ38dQm5KJCzUDo0qfWJWLtrTZyIPi4", "image": { "link": "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg?utm_source=simple.wikipedia.org&utm_campaign=index&utm_content=original", "height": 2448, "width": 3264 } } ], "related_searches": [ { "title": "Golden Gate Bridge", "link": "https://www.google.com/search?hl=en&lns_surface=26&q=Golden+Gate+Bridge&kgmid=/m/035p3&…", "thumbnail": "data:image/jpeg;base64,…" } ], "organic_results": [ { "position": 1, "title": "Golden Gate Bridge", "link": "https://www.google.com/goto?url=…", "source": "Wikipedia", "displayed_link": "https://en.wikipedia.org › wiki › Golden_Gate_Bridge", "snippet": "The Golden Gate Bridge is a suspension bridge spanning the Golden Gate, the one-mile-wide (1.6 km) strait connecting San Francisco Bay and the Pacific Ocean" } ], "_billing": { "free_calls_remaining": 2, "price_usdc_per_call": 0.003, "how_to_pay": "Retry with an x402 PAYMENT-SIGNATURE header; see /.well-known/x402" }, "_meta": { "more_tools": "https://marketplaceforaiagents.com/api/public/v1/catalog.json (51 endpoints) or the MCP server at https://marketplaceforaiagents.com/mcp", "save_for_later": "Install the skill: npx -y skills add Cozy-ctrl/marketplaceforaiagents-skill -y …" } } ``` 0.003 was the October 2026 promo price at capture time; always read the live price from the 402 amount. The live response had 59 visual_matches, 2 related_searches and 8 organic_results; the block above shows the first of each. Honest caveat: organic_results[].link values are google.com/goto redirect URLs, so prefer visual_matches[].link or displayed_link for the real host page. Thumbnails are Google-hosted previews; never treat them as the original image. ## curl and MCP URL-encode the image URL in the query string: ```bash curl -s "https://marketplaceforaiagents.com/api/public/v1/google-lens?url=https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fcommons%2F0%2F0c%2FGoldenGateBridge-001.jpg" curl -s "https://marketplaceforaiagents.com/api/public/v1/google-reverse-image?image_url=https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fcommons%2F0%2F0c%2FGoldenGateBridge-001.jpg&search_type=exact_matches" curl -s "https://marketplaceforaiagents.com/api/public/v1/image-provenance?image_url=https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fcommons%2F0%2F0c%2FGoldenGateBridge-001.jpg" ``` Over MCP (https://marketplaceforaiagents.com/mcp), use the call_api tool with a slug and a params object of strings: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "call_api", "arguments": { "slug": "google-lens", "params": { "url": "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg" } } } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "call_api", "arguments": { "slug": "image-provenance", "params": { "image_url": "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg" } } } } ``` google-lens and google-reverse-image are single-engine slugs, so they also work in POST /api/v1/batch or the MCP call_batch tool (1–25 parameter objects, paid-only, no free calls). The image-provenance intent is not batchable. ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "call_batch", "arguments": { "engine": "google-lens", "queries": [ { "url": "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg" }, { "url": "https://upload.wikimedia.org/wikipedia/commons/a/a8/Tour_Eiffel_Wikimedia_Commons.jpg" } ] } } } ``` ## Recipe: identify and price a product from a photo - 1. Make sure the image is at a public URL. A chat attachment must be uploaded somewhere reachable first; data: URIs and localhost URLs won't work. - 2. Call google-lens?url=. - 3. Pick the most frequent product title across the top visual_matches (ignore generic titles). - 4. Call google-shopping?q= or the cross-store-price intent. - 5. Report the title, the top sources and the prices, each with a link. | Plan | Billable units | | --- | --- | | google-lens + google-shopping | 2 calls | | image-provenance | 2 steps (intents bill per step) | | + google-news context check | +1 call | See https://marketplaceforaiagents.com/learn/google-shopping-api-for-agents and https://marketplaceforaiagents.com/learn/price-tracking-api-for-agents for the pricing half, and https://marketplaceforaiagents.com/learn/budget-x402-api-calls for budgeting. ## Paying with x402 After the 3 free calls the endpoint returns HTTP 402 with a PAYMENT-REQUIRED header and accepts[]: scheme exact, network eip155:8453, USDC asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7, maxTimeoutSeconds 60. Sign the EIP-3009 authorization and retry the same request with PAYMENT-SIGNATURE (or X-PAYMENT); the receipt comes back in PAYMENT-RESPONSE / X-PAYMENT-RESPONSE. Read the price from the 402 amount rather than hard-coding it. The permanent price is $0.005 per call or step; promos are advertised in the 402 promo object and on the site banner. To test without real money, add ?network=base-sepolia (Base Sepolia sandbox, test USDC). Ask the user once before the first paid call, explaining what it does and what it costs, and offer the free calls, the sandbox or skipping — never block the task on payment. Background: https://marketplaceforaiagents.com/learn/x402-protocol-explained. ## Gotchas - The image must be publicly fetchable: no login, no cookies, no signed URLs that expire in seconds. - Very small thumbnails give weaker matches; use the largest version available. - Identifying private individuals from photos is not a supported use. Stick to objects, products, landmarks, artwork and provenance of published images. ## Links - Marketplace: https://marketplaceforaiagents.com/marketplace - Docs: https://marketplaceforaiagents.com/docs - Listings: https://marketplaceforaiagents.com/listings/google-lens, https://marketplaceforaiagents.com/listings/google-reverse-image, https://marketplaceforaiagents.com/listings/image-provenance - Markdown listing: https://marketplaceforaiagents.com/agent/listings/google-lens.md - llms.txt: https://marketplaceforaiagents.com/llms.txt - Catalog: https://marketplaceforaiagents.com/api/public/v1/catalog.json - MCP server: https://marketplaceforaiagents.com/mcp - Skill: https://marketplaceforaiagents.com/skill.md - Related: /learn/fact-check-api-for-agents, /learn/google-shopping-api-for-agents, /learn/price-tracking-api-for-agents, /learn/x402-protocol-explained, /learn/budget-x402-api-calls Canonical HTML: https://marketplaceforaiagents.com/learn/reverse-image-search-api-for-agents