README.md

---
title: DeepFakeScanner
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: AI-generated & manipulated image detection (v0.4.0)
---

# DeepFakeScanner

A commercial deepfake / AI-generated image detection service.

## What it is

A FastAPI web service that scans an uploaded image and returns a structured
verdict: `authentic`, `ai_generated`, `deepfake`, `edited`, or `uncertain` —
with per-class probabilities, per-detector signals, and a C2PA provenance
check.

## Live

| | URL |
|---|---|
| Frontend | https://veridicate.com |
| API | https://api.veridicate.com |
| Source (HF mirror) | https://huggingface.co/spaces/veridicate/scanner |

## Status

**Stage 2 deployed (`v0.3.0-stage2`).** The CLIP classifier head was
fine-tuned on a 100k commercially-licensed dataset (50k Open Images +
50k Flux.1-schnell) and is currently serving real predictions in
production.

In-distribution test-set metrics (10k held-out images):
- Accuracy: **98.44%**
- Precision (AI class): 98.25%, recall: 98.64%, F1: 98.44%

**Stage 3A wired + verified 2026-05-30 (`v0.4.0-stage3a`); ships to
production on merge of `feat/akila-20260515 → main`.** Multi-generator
dataset built: 50k Flux + 20k SDXL + 20k SD 3.5 Medium + 10k AuraFlow
on the AI side, matched authentic from Open Images V7. SDXL held out of
training so the heldout split is a true generalisation test. The trained
head (`head_v3a.pt`) is published to the private HF Hub repo, the runtime
config now defaults to it (`config.py`), and a filtered, test-gated
GitHub Action deploys the inference service on merge. Headline verified
numbers vs the Stage 2 baseline:

| Split | Baseline | Candidate | Δ |
|---|---|---|---|
| heldout SDXL (UNSEEN in training) | 83.93% | **89.48%** | **+5.55 pp** |
| test (in-distribution) | 96.47% | 98.43% | +1.96 pp |
| test_augmented (robustness) | 93.96% | 98.41% | +4.46 pp |

The +5.55 pp on the SDXL holdout is the load-bearing number — SDXL was
held entirely out of training, so it's the closest available proxy for
how the model will behave on generators it never saw. The
family-fingerprint approach (train on a diverse mix of open
generators, inherit coverage of closed generators) is validated.
Detailed audit trail in
[`docs/stage3a-implementation.md`](docs/stage3a-implementation.md).

**Known limitation (until the Stage 3A merge deploys):** the live
model is still the Stage 2 head, trained on Flux.1-schnell only. Other
generators (Gemini/Imagen 3, DALL-E 3, Midjourney, Grok, Stable
Diffusion) are out-of-distribution for the *currently-live* model and
it often returns `uncertain` verdicts. The Stage 3A head (queued to
ship) closes most of this gap. Rollback is a one-line env override
(`MODEL_VERSION` + `HEAD_CHECKPOINT_HF_FILENAME`) — both heads live in
the same private HF Hub repo.

## Roadmap at a glance

| Stage | What it delivers | Status |
|---|---|---|
| **1** | Working website, API, deploy pipeline. Detector returns random guesses. | ✅ Done |
| **2** | A trained classifier — 98% accurate on Flux-family AI images. | ✅ Done, live (`v0.3.0-stage2`) |
| **3A** | Broad coverage across the AI image-generation landscape — CLIP head retrained on Flux + SDXL + SD 3.5 + AuraFlow. | ✅ Wired + verified 2026-05-30 (`v0.4.0-stage3a`); ships on merge to `main` |
| **3B** | Frequency-artifact detector (FFT/DCT, generator-agnostic) brought online. | 🔭 Queued after Stage 3A ships |
| **4** | Production scale: faster hosting, paid tier, user accounts. | ⏸️ After Stage 3 |
| **5** | Enterprise capability: licensed paid-API training data, face-swap detection, adversarial robustness. | 🔭 Future |

Full roadmap with per-stage strengths, weaknesses, and how each
weakness gets fixed: [`docs/plan.md`](docs/plan.md). Plain-English
summary up front; technical detail below; glossary at the end for
non-technical readers.

## Quick start

```bash
# CPU PyTorch first (lean install)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
pip install -e .

# Pre-download CLIP weights
python scripts/download_weights.py

# Run the server
uvicorn deepfake_scanner.api.v1:app --reload --port 7860
```

Then:

```bash
curl -F "file=@some_image.jpg" http://localhost:7860/v1/scan/image | jq
```

Or against the live API:

```bash
curl -F "file=@some_image.jpg" https://api.veridicate.com/v1/scan/image | jq
```

Dataset-generation dependencies are documented in the optional GPU section of
[`requirements.txt`](requirements.txt). Keep those packages out of the
production inference image.

## API

- `GET  /health` — liveness probe
- `GET  /v1/info` — model + config metadata
- `POST /v1/scan/image` — scan an image (multipart/form-data, max 10 MB,
  JPEG/PNG/WebP)

See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the full response schema.

## Privacy

Visitor uploads are processed in-memory and **never persisted**. Only scan
metadata (verdict, confidence, latency, model version) is recorded.

## Documentation

- [`docs/plan.md`](docs/plan.md) — **product roadmap** with per-stage
  strengths, weaknesses, and fix paths. Written so a non-technical
  reader can follow the strategy, with deeper technical detail and a
  glossary inline.
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — technical design of the
  detection pipeline + API contract
- [`docs/decisions.md`](docs/decisions.md) — running decision log
  (good context if picking up this project later)
- [`NOTICES.md`](NOTICES.md) — third-party licensing record
- [`CLAUDE.md`](CLAUDE.md) — project context (auto-loaded by Claude Code)
- [`scripts/dataset/README.md`](scripts/dataset/README.md) — dataset curation pipeline

## License

Apache 2.0.