# Perceptual Image Hash API
> Fingerprint images for near-duplicate detection and similarity. Compute the three classic perceptual hashes — aHash (average), dHash (difference) and pHash (DCT-based) — as 64-bit hex values for any image (by URL or base64), then compare two images to get the Hamming distance and a 0-100 similarity score per algorithm, with a likely-same flag. Unlike a cryptographic hash, perceptual hashes stay close when images are resized, recompressed or lightly edited — so you can spot duplicates, find re-uploads, cluster similar pictures and power reverse-image matching. Fully local (no third-party service), nothing stored. Supports PNG, JPEG, BMP, TIFF and GIF. Live. 3 endpoints. Distinct from basic image-info/resize and from string-similarity tools.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/imghash-api/..."
```

## Pricing
- **Free** (Free) — 1,560 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 31,000 calls/Mo, 8 req/s
- **Pro** ($27/Mo) — 188,000 calls/Mo, 20 req/s
- **Mega** ($63/Mo) — 960,000 calls/Mo, 50 req/s

## Endpoints

### Hash

#### `GET /v1/compare` — Compare two images

**Parameters:**
- `url1` (query, required, string) — First image URL Example: `https://raw.githubusercontent.com/ianare/exif-samples/master/jpg/gps/DSCN0010.jpg`
- `url2` (query, required, string) — Second image URL Example: `https://raw.githubusercontent.com/ianare/exif-samples/master/jpg/gps/DSCN0010.jpg`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imghash-api/v1/compare?url1=https%3A%2F%2Fraw.githubusercontent.com%2Fianare%2Fexif-samples%2Fmaster%2Fjpg%2Fgps%2FDSCN0010.jpg&url2=https%3A%2F%2Fraw.githubusercontent.com%2Fianare%2Fexif-samples%2Fmaster%2Fjpg%2Fgps%2FDSCN0010.jpg"
```

**Response:**
```json
{
    "data": {
        "hashes": {
            "image1": {
                "ahash": "fcfffff310100000",
                "dhash": "313c156666e4e584",
                "phash": "4edbd88c49eaf808"
            },
            "image2": {
                "ahash": "fcfffff310100000",
                "dhash": "313c156666e4e584",
                "phash": "4edbd88c49eaf808"
            }
        },
        "comparison": {
            "ahash": {
                "distance": 0,
                "similarity": 100
            },
            "dhash": {
                "distance": 0,
                "similarity": 100
            },
            "phash": {
                "distance": 0,
                "similarity": 100
            }
        },
        "likely_same": true,
        "average_similarity": 100
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:01.433Z",
        "request_id": "63dd58de-3f23-4e04-83bd-8fc695338515"
    },
    "status": "ok",
    "message": "Compare two images",
    "success": true
}
```

#### `GET /v1/hash` — Perceptual hash of an image

**Parameters:**
- `url` (query, required, string) — Image URL (or use image= base64) Example: `https://raw.githubusercontent.com/ianare/exif-samples/master/jpg/gps/DSCN0010.jpg`
- `algorithm` (query, optional, string) — ahash|dhash|phash|all

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imghash-api/v1/hash?url=https%3A%2F%2Fraw.githubusercontent.com%2Fianare%2Fexif-samples%2Fmaster%2Fjpg%2Fgps%2FDSCN0010.jpg"
```

**Response:**
```json
{
    "data": {
        "ahash": "fcfffff310100000",
        "dhash": "313c156666e4e584",
        "phash": "4edbd88c49eaf808"
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:01.770Z",
        "request_id": "dd81ac2e-8957-40fc-9c3e-81db1bf08e79"
    },
    "status": "ok",
    "message": "Perceptual hash of an image",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/imghash-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "auth": "none upstream; this gateway requires x-api-key",
        "name": "Perceptual Image Hash API",
        "note": "Compute aHash, dHash and pHash (64-bit, hex) for an image — /v1/hash?url= or ?image= (base64), optional ?algorithm=ahash|dhash|phash|all. Compare two images via /v1/compare?url1=&url2= → Hamming distance and similarity % per algorithm, with a likely_same flag. For near-duplicate detection and reverse-image matching. Distinct from image-api and similarity-api (strings). Live, nothing stored.",
        "source": "Local hashing (Jimp) — no key, no upstream",
        "endpoints": 3
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:01.867Z",
        "request_id": "bc2a4926-c87d-445f-9cfd-1dac892a7924"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/imghash-api
OpenAPI spec: https://www.oanor.com/api/imghash-api/openapi.json