Hash lists

A hash list holds fingerprints of images your project never wants again. Every image upload is fingerprinted and compared with the project's lists, so a re-upload of a listed image is caught even after it is resized, recompressed, brightened or re-saved in another format. The fingerprint is the image's PDQ  perceptual hash, the format shared lists of known images use. Every image asset reports its own as content.image.perceptualHash, with content.image.perceptualHashQuality. See Asset lifecycle.

Flag and block lists

Each list has an action:

• Flag records the match on the asset and in an asset.hash-matched event, without changing the moderation decision. Use it to watch for content you want to review or count.
• Block blocks close matches, 16 bits apart or fewer, and flags looser ones up to 31 bits apart. Use it for images you have already decided to remove.

A block raises the decision to at least blocked; a stricter policy decision, such as purged, still applies. A per-upload flaggedContentPolicy override takes precedence over hash lists. Changing a list's action applies to later uploads.

How matching works

Two PDQ hashes are compared by counting the bits that differ, from 0 (the same picture) to 256. Copies of the same image are usually within a few bits; unrelated images are around 128 bits apart.

• Matches 31 bits apart or fewer are recorded, closest first, up to 10 per asset.
• Hashes with a quality below 50 come from flat or featureless images and are never matched, on either side.
• Visually similar images can match: two posts made from the same meme template, or screenshots of the same app screen. Use flag lists while you learn what your lists catch.

Matches appear on the asset as classification.moderation.hashMatches, each with its list, entry, distance and the action it took. When a block list decides the asset, classification.moderation.policy.decision.source is hash-list.

Add images to a list

Create and manage lists in Portal › Hash lists, where you can add an image from its asset page or paste a hash computed elsewhere.

With the API, create a list with POST /projects/:projectId/hash-lists:

{ "name": "Removed images", "action": "block" }

Then add an image asset to it with POST /hash-lists/:hashListId/entries:

{ "assetId": "8f7d2c1e-4b3a-4c5d-9e8f-1a2b3c4d5e6f", "label": "Report 1042" }

Send hash (64 hexadecimal characters) and, when you know it, quality instead of assetId to add a hash computed elsewhere. Adding a hash the list already holds returns the existing entry. Removing an entry stops later uploads matching it; assets already decided keep their decision.

A project can hold 50 lists and 10,000 entries across them. Managing lists needs the hash-lists:write permission. See the Hash lists API reference.