Skip to main content
POST
/
v1
/
risk
/
deepfake
/
scan
Deepfake scan
curl --request POST \
  --url https://api.truthlocks.com/v1/risk/deepfake/scan \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "subject_ref": "<string>",
  "media_url": "<string>",
  "media_type": "image",
  "callback_url": "<string>"
}
'
{
  "scan_id": "<string>",
  "status": "<string>",
  "subject_ref": "<string>"
}

​
How detection works

Scans use a heuristic signal engine (heuristic_v1) that accepts caller-provided signals (from external ML models, rule engines, or manual review) and maps them to weighted scores:
  • Deepfake indicators: face swap, inconsistent lighting, compression artifacts, temporal inconsistency, metadata mismatch
  • Impersonation indicators: biometric mismatch, name mismatch, identity doc mismatch, issuer trust violation
Scores ≥ 75 set verdict deepfake or impersonation. Scores ≥ 40 set suspect. Scores ≥ 60 automatically ingest a risk signal. You can also bypass heuristic analysis by passing pre-computed deepfake_score and impersonation_score values directly. The platform still applies the same verdict thresholds and automatic signal ingestion. See the deepfake detection guide for the full workflow, indicator reference, and additional examples.

​
Request

​
subject_ref
string
required
Reference to the subject being scanned — URL, SHA-256 hash, attestation ID, or any opaque identifier.
​
subject_type
string
required
Type of subject: image, video, document, attestation, identity
​
signals
array
Array of indicator strings from your external model or rules engine (e.g. ["face_swap_detected", "metadata_mismatch"]). When provided without pre-computed scores, the heuristic engine maps these to weighted deepfake and impersonation scores.
​
attestation_id
string
UUID of an attestation to associate with this scan result. Use this to tie detection results to the credential they relate to.
​
deepfake_score
integer
Pre-computed deepfake score (0–100) from an external model. If provided along with impersonation_score, heuristic analysis is skipped.
​
impersonation_score
integer
Pre-computed impersonation score (0–100) from an external model.

​
Response

​
scan_id
string
UUID of the scan result.
​
subject_ref
string
The subject reference that was scanned.
​
subject_type
string
Type of subject: image, video, document, attestation, identity
​
deepfake_score
integer
Deepfake probability score (0–100).
​
impersonation_score
integer
Impersonation probability score (0–100).
​
verdict
string
authentic | suspect | deepfake | impersonation
​
indicators
array
List of triggered indicators from the scan.
​
detection_model
string
Detection model used (e.g. heuristic_v1).
​
signal_id
string
UUID of the auto-ingested risk signal (only present when score ≥ 60).
​
attestation_id
string
UUID of the linked attestation, if one was provided during the scan.
​
created_at
string
ISO 8601 timestamp of when the scan was performed.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
subject_ref
string
required

Reference identifier for the subject

​
media_url
string
required

URL of the media to scan

​
media_type
enum<string>
Available options:
image,
video,
audio
​
callback_url
string

Webhook URL for async results

Response

Scan initiated

​
scan_id
string
​
status
string
​
subject_ref
string