Comparison API

Overview

The DiffALL API runs the same comparison engine as the website. Send two files of the same type — images, video, audio, subtitles, or text — and get back a similarity score from 0 to 100, plus a short verdict.

• Auth: an X-API-Key header on every request.
• Cost: one credit per successful comparison — the same balance as the website.
• Server-side only: no CORS headers are set; call it from your backend or scripts, not the browser.

1. Get an API key

Sign in to DiffALL, then open the API Keys panel on the home page and click + New key. Your key (it looks like dk_live_…) is shown once — copy it immediately. We only ever store a hash, so a lost key can't be recovered; just revoke it and create a new one.

Sign in & create a key →

2. Compare two files

Send a multipart/form-data POST with fields file1 and file2. For images, add mode=feature for rotation/lighting-tolerant matching.

Images, subtitles & text — instant result

curl -X POST https://diff-all.com/api/v1/compare \
  -H "X-API-Key: dk_live_your_key_here" \
  -F file1=@before.png \
  -F file2=@after.png

{
  "status": "done",
  "similarity": 92.4,
  "type": "image",
  "verdict": "Moderate similarity — files share significant content"
}

Video & audio — asynchronous

These take longer, so the API returns a job_id with HTTP 202. Poll the status_url until status is done.

# 1. start the job
curl -X POST https://diff-all.com/api/v1/compare \
  -H "X-API-Key: dk_live_your_key_here" \
  -F file1=@a.mp4 -F file2=@b.mp4
# → 202 {"status":"processing","job_id":"<uuid>","status_url":"/api/v1/compare/<uuid>"}

# 2. poll until done
curl https://diff-all.com/api/v1/compare/<uuid> \
  -H "X-API-Key: dk_live_your_key_here"
# → {"status":"processing","progress":42}   …then…
# → {"status":"done","similarity":88.1,"type":"video","verdict":"…"}

Endpoints

Method & path	Description
POST /api/v1/compare	Upload file1 + file2. Returns the score (image/subtitle/text) or a job_id (video/audio).
GET /api/v1/compare/<job_id>	Poll an async job until status is done.

Response fields

Field	Meaning
similarity	The headline score, 0–100 (higher = more similar).
type	Detected media type: image, video, audio, subtitle, or text.
verdict	A one-line human summary of the score.
status	done, processing, queued, or error.

Status codes

Code	Meaning
200	Success (synchronous result, or a poll response).
202	Async job accepted — poll the status_url.
400	Bad input (missing file, unsupported type, mismatched types, too long).
401	Invalid or missing API key.
402	No credits remaining.
413	File too large.
422	Files could not be compared (e.g. unreadable).
429	Rate-limited — 3/second and 60/minute per key.

Limits

• Files of the same type only (two images, two videos, etc.).
• Video and audio are capped at 1 minute in the current version.
• Rate limit: 3 requests/second and 60/minute per key.
• Each successful comparison costs one credit.

Frequently asked questions

How do I compare two images via an API?

Send a multipart POST to /api/v1/compare with fields file1 and file2 plus your X-API-Key header. Images return a 0–100 similarity score immediately.

Does the comparison API have a free tier?

Yes — every account gets 10 free comparisons per day, and each API call costs one credit from the same balance as the website. Buy 50 more for a one-time $5, or contact sales for an unlimited Enterprise plan.

What file types does the API support?

Images (JPG, PNG, WebP, GIF), video (MP4, AVI, MOV, MKV), audio (MP3, WAV, FLAC, AAC), subtitles (SRT, VTT), and text/JSON/CSV/XML. Both files in a request must be the same type.

How does the API compare video and audio?

Asynchronously — the POST returns a job_id with HTTP 202, and you poll GET /api/v1/compare/<job_id> until the status is done.

What is the API rate limit?

3 requests per second and 60 per minute per key. Each successful comparison also costs one credit.