Documentation
MediaLayer API docs
Everything you need to index media libraries, run similarity search, integrate the Match API, and reduce AI vision costs with the Cost Optimizer.
What is MediaLayer?
A fingerprint-based media matching API for detecting duplicates at scale.
MediaLayer lets you build content duplication detection into your product. You index a library of images, audio, or video — then query it with any media clip and get back matches ranked by similarity — designed for sub-second retrieval across large indexed libraries.
The core workflow is two steps: Index (submit media → fingerprint stored) and Search (submit a query → ranked matches returned). Fingerprinting is classical signal processing — not ML — so it is fast, deterministic, and encoding-agnostic.
🖼 Image
Handles
- ✓ Near-duplicate images
- ✓ Watermark overlays
- ✓ Minor crop / resize
Does not handle
- ✗ Flipped / mirrored
- ✗ Style transfer
🎵 Audio
Handles
- ✓ Re-encoded tracks
- ✓ Volume changes
- ✓ Clip from middle of track
Does not handle
- ✗ Pitch shift
- ✗ Heavy noise cover
🎬 Video
Handles
- ✓ Transcodes / re-uploads
- ✓ Brightness & contrast edits
- ✓ Segment extraction
Does not handle
- ✗ Horizontal flip
- ✗ Heavy visual filters
Projects
Projects isolate your indexed media libraries. Each project has its own fingerprint store.
A Project is a tenant — an isolated container for indexed media and search queries. Each project has its own API keys and its own quota counters. Media indexed in Project A is never searchable from Project B.
When to create separate projects
- You serve multiple customers and need data isolation between them
- You have separate environments (staging vs production) that should not share fingerprints
- You want independent quota tracking per library
API keys are always scoped to one project — a key from Project A cannot index or search Project B's library.
Roles & Permissions
Three-tier access model: Owner, Admin, and Member.
Can
- ✓ Everything Admins can do
- ✓ Manage billing and plan upgrades
- ✓ Cannot be removed from the organization
Cannot
- ✗ Be demoted — Owner role is permanent
Can
- ✓ Invite and remove team members
- ✓ Promote members to Admin
- ✓ Create, rotate, and revoke API keys
- ✓ Index and search media
- ✓ View usage and billing
Cannot
- ✗ Remove the Owner
- ✗ Change the Owner's role
Can
- ✓ Index and search media
- ✓ View indexed assets and jobs
- ✓ View usage statistics
Cannot
- ✗ Invite or remove team members
- ✗ Create or revoke API keys
- ✗ Manage billing
Indexing Media
Submit media to build your searchable fingerprint library.
Indexing extracts a fingerprint— a compact representation of the media's perceptual content — and stores it in the library. Once indexed and in ready status, the asset can be matched against any incoming search query.
Ingest modes
| Mode | How |
|---|---|
| Single URL | POST /v1/index/{type}/url with a public URL — background fingerprinting |
| File upload | POST /v1/index/{type}/upload with a file body — bytes stored and fingerprinted |
| CSV bulk | Upload a CSV (url, media_type, name) to trigger one task per row |
| ZIP bulk | Provide a ZIP URL with an internal manifest.csv — worker processes all files |
Asset status lifecycle
pending→processing→ready|failedOnly ready assets are matched during search. A failed asset did not fingerprint successfully — check the URL is publicly accessible and the media is valid.
You must have indexed media before searching
The search endpoint will return no matches if your project has no ready assets for the chosen media type.
Searching
Submit a query and receive ranked matches from your library.
A search query fingerprints the incoming media on the fly and compares it against every indexed asset in the library. Results are ranked by similarity and coverage.
similarity (0.0–1.0)
How visually or acoustically close the best-matching portion is. A score of 1.0 means an exact perceptual match. Threshold filters out results below this value.
coverage (video/audio only)
Fraction of the query that matched consistently with the same temporal offset. A single lucky frame can score 0.95 — but coverage: 0.9 means 9 of 10 query segments matched. For duplication detection, check coverage, not just similarity.
Threshold guidance
| Media type | Suggested threshold | Notes |
|---|---|---|
| Image | 0.85 | Good for near-duplicate detection with minor edits |
| Audio | 0.80 | Lower because re-encoding introduces small variations |
| Video | 0.75 | Use coverage ≥ 0.7 alongside for strong duplication signal |
API Keys
Server-side credentials for the /v1 API. Never expose in the browser.
API keys authenticate your server-side code with the /v1/* endpoints. Each key carries a set of scopes — explicit grants for which operations the key may perform.
Scopes
image:indeximage:searchaudio:indexaudio:searchvideo:indexvideo:searchassets:readassets:deletejobs:readusage:readServer-side only
API keys must never appear in browser code, mobile apps, or client-side JavaScript.
Best practices
- Store keys in environment variables — never hard-code
- Create one key per service, scoped to only what that service needs
- Rotate keys regularly and immediately after any suspected exposure
- Revoke compromised keys instantly from the API Keys page
Billing & Quotas
Plans are priced by indexed asset capacity and Search Processing — not raw query count.
Quota types
Search Processing
Primary billing metric. Measures total bytes of media downloaded and fingerprinted during search queries. Larger files and longer videos consume more Search Processing than small image searches. Resets monthly.
Search query count
Soft abuse limit on total number of search requests per billing period. Not the primary pricing dimension — plans are priced by Search Processing, not query count.
Indexed asset caps
Absolute limits on how many images, audio, and video files can be in ready status. These do not reset monthly.
Feature flags
Per-plan toggles for image, audio, and video indexing/search. If disabled, the endpoint returns 403 regardless of quota.
When you approach a quota limit, MediaLayer sends an email alert. At 100% the affected operation returns 429 quota_exceeded until the period resets or you upgrade your plan.