Deepfake and impersonation detection

The deepfake and impersonation detection API lets you scan images, videos, documents, attestations, and identities for signs of manipulation or fraud. Scans that exceed the risk threshold automatically create a risk signal, connecting detection directly to the Anti-Fraud Identity Firewall pipeline.

Deepfake detection is part of the Anti-Fraud Identity Firewall. Scan results flow into the same risk signal pipeline as other fraud signals, so you can query and review them from the Risk & Fraud > Signals console page or the list signals endpoint.

How it works

Submit a scan

Send a POST request to /v1/risk/deepfake/scan with a subject reference and either raw indicator signals from your detection pipeline or pre-computed scores from an external model.

Review the verdict

The response includes deepfake and impersonation scores (0–100) and a verdict: authentic, suspect, deepfake, or impersonation.

Automatic signal creation

When a score reaches 60 or above, the platform automatically ingests a risk signal into your tenant’s pipeline. The response includes the signal_id so you can trace it.

Retrieve results later

Use GET /v1/risk/deepfake/results/{subject_ref} to fetch the latest scan result for any previously scanned subject.

Prerequisites

An active Truthlocks tenant with an API key
Subject references for the content you want to scan (URLs, SHA-256 hashes, attestation IDs, or opaque identifiers)

Scanning a subject

Submit a scan with indicator signals from your detection pipeline:

curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "image",
    "signals": ["face_swap_detected", "inconsistent_lighting"]
  }'

const response = await fetch("https://api.truthlocks.com/v1/risk/deepfake/scan", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject_ref: "sha256:a1b2c3d4...",
    subject_type: "image",
    signals: ["face_swap_detected", "inconsistent_lighting"],
  }),
});
const result = await response.json();

import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/deepfake/scan",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "subject_ref": "sha256:a1b2c3d4...",
        "subject_type": "image",
        "signals": ["face_swap_detected", "inconsistent_lighting"],
    },
)
result = resp.json()

The response includes scores, a verdict, and (if the threshold was met) a linked risk signal:

{
  "scan_id": "7c8d9e0f-...",
  "subject_ref": "sha256:a1b2c3d4...",
  "subject_type": "image",
  "deepfake_score": 60,
  "impersonation_score": 0,
  "verdict": "suspect",
  "indicators": ["face_swap_detected", "inconsistent_lighting"],
  "detection_model": "heuristic_v1",
  "signal_id": "9f3a1c2d-...",
  "created_at": "2027-05-22T10:00:00Z"
}

Detection model

The platform uses a heuristic signal engine (heuristic_v1) that maps caller-provided indicators to weighted scores. The engine evaluates 12 indicators across two categories:

Deepfake indicators

Indicator	Description
`face_swap_detected`	Face replacement or morphing detected
`inconsistent_lighting`	Lighting inconsistencies across the subject
`compression_artifacts`	Unusual compression patterns suggesting manipulation
`temporal_inconsistency`	Frame-level inconsistencies in video content
`metadata_mismatch`	File metadata doesn’t match expected patterns

Impersonation indicators

Indicator	Description
`biometric_mismatch`	Biometric data doesn’t match the claimed identity
`name_mismatch`	Name on identity document doesn’t match records
`identity_doc_mismatch`	Identity document appears altered or inconsistent
`issuer_trust_violation`	Issuer trust level is insufficient for the claim

Verdicts and thresholds

Each scan produces a verdict based on the highest score:

Score range	Verdict	Meaning
0 – 39	`authentic`	No significant indicators detected
40 – 74	`suspect`	Some indicators present — review recommended
75 – 100	`deepfake` or `impersonation`	High confidence detection — which verdict depends on the dominant score

When either score reaches 60 or above, the platform automatically creates a risk signal. You don’t need to make a separate API call — the signal_id is returned in the scan response.

Using pre-computed scores

If you already have scores from an external ML model or detection service, pass them directly to skip heuristic analysis:

curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "video",
    "deepfake_score": 82,
    "impersonation_score": 15
  }'

The platform still applies the same verdict thresholds and automatic signal ingestion, so you get consistent classification regardless of the detection source.

Linking scans to attestations

Associate a scan with an existing attestation to tie detection results to the credential they relate to:

curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "sha256:a1b2c3d4...",
    "subject_type": "attestation",
    "signals": ["biometric_mismatch", "identity_doc_mismatch"],
    "attestation_id": "660e8400-e29b-41d4-a716-446655440001"
  }'

This makes it easier to flag and review suspicious attestations in the console.

Retrieving scan results

Fetch the latest scan result for a subject without re-running the scan:

curl https://api.truthlocks.com/v1/risk/deepfake/results/sha256:a1b2c3d4... \
  -H "X-API-Key: tl_live_..."

Subject types

The subject_type field tells the platform what kind of content is being scanned:

Type	Use case
`image`	Photos, ID documents, profile pictures
`video`	Video recordings, live captures
`document`	PDFs, scanned documents
`attestation`	Credentials issued through the platform
`identity`	Identity claims, KYC submissions

Usage metering

Each deepfake scan request increments the antifraud.deepfake_scans usage counter for your billing cycle. You can monitor your scan consumption with the usage API or in the console at Settings > Billing > Usage under the Anti-Fraud section.

Deepfake scan quotas vary by plan tier. See the billing overview for details on all Anti-Fraud metered products.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

How it works

Prerequisites

Scanning a subject

Detection model

Deepfake indicators

Impersonation indicators

Verdicts and thresholds

Using pre-computed scores

Linking scans to attestations

Retrieving scan results

Subject types

Usage metering

What’s next

​How it works

​Prerequisites

​Scanning a subject

​Detection model

​Deepfake indicators

​Impersonation indicators

​Verdicts and thresholds

​Using pre-computed scores

​Linking scans to attestations

​Retrieving scan results

​Subject types

​Usage metering

​What’s next

How it works

Prerequisites

Scanning a subject

Detection model

Deepfake indicators

Impersonation indicators

Verdicts and thresholds

Using pre-computed scores

Linking scans to attestations

Retrieving scan results

Subject types

Usage metering

What’s next