Image Similarity & Duplicate Detection API
Give it two public HTTPS image URLs; it tells you whether they’re byte-identical and how visually similar they are. No file storage — images are fetched, hashed, and discarded.
Overview
This API compares two image URLs. It first checks for an exact byte-for-byte match (SHA-256), and if the images aren’t identical, falls back to a perceptual hash (dHash) to score how visually similar they are — robust to re-compression or resizing.
Supported image formats: PNG, JPEG, and WebP. Both URLs must be HTTPS; redirects are not followed.
Request
Query Parameters
url1stringYesHTTPS URL of the first image
url2stringYesHTTPS URL of the second image
Example Request
curl "https://api.apiespresso.com/v1/compare?url1=https://example.com/a.png&url2=https://example.com/b.png" \ -H "Authorization: Bearer idk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response
Success response (200 OK):
{
"exact_match": false,
"similarity_score": 0.9219,
"hash_type": "dhash",
"distance": 5
}
Fields
exact_matchTrue if the two images are byte-for-byte identical (SHA-256 match). When true, similarity_score is 1 and distance is 0 without running the perceptual comparison.
similarity_score0–1, higher means more visually similar.
hash_typeAlways "dhash" (difference hash) in this MVP.
distanceHamming distance between the two 64-bit perceptual hashes (0–64, lower is more similar).
Errors
All errors return {"error": "<message>"} with a client-safe message — no stack traces, internal paths, or storage details.
400Missing/malformed url1/url2, non-https URL, or a URL that resolves to a disallowed (private/internal/metadata) destination
401Missing/invalid Authorization header or an unknown/revoked API key
403Monthly quota exceeded
422URL fetch failed, redirected, returned a non-image or unsupported content-type, exceeded the size limit, or the image couldn’t be decoded
429Rate limit exceeded (Retry-After header included)
500Unexpected internal error
Pricing
Requests beyond your plan's monthly limit will be blocked until you upgrade or your next billing cycle starts.