~/docs cat create-detection.md

Create a detection

POST /v1/detections — run a detection on one file. The server infers image, video, or audio, runs the right detectors, and answers with one envelope. Synchronous.

Request (multipart/form-data):

request fields

file    binary   the media — image ≤ 10 MB, video ≤ 100 MB, audio ≤ 50 MB
url     string   a video link, as an alternative to file
save    string   "true" | "false" — persist history + file (default "true")

Idempotency-Key: <key>   optional header — a resend within 24 h replays the
                         stored answer instead of re-billing

curl

curl -X POST "https://api.scam.ai/v1/detections" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -F "file=@/path/to/media.mp4"

response fields

id             string   detection id (null when save="false")
object         string   always "detection"
status         string   always "completed"
created_at      string   ISO timestamp
media          object   { type: "image" | "video" | "audio",
                          filename, mime_type, bytes }
model          object   { name, version, variant } — the detector that ran
verdict        string   "LIKELY_AUTHENTIC" | "LIKELY_FORGED"  (branch on this)
risk_score     number   0–100, ordering within a verdict band
confidence     float    0.0–1.0 (nullable)
summary        string   one human-readable sentence (nullable)
classes        array    [{ class, score }] — per-class scores
checks         array    [{ name, model, confidence }] — per-detector detail
frames_metered number   frames billed (video)
cost_usd       number   dollar cost of this detection
credits_used   number   credits actually debited — prefer this over any quote

verdict is the same two-value enum for every media type; the media-specific detail rides in classes and checks. This powers deepfake detection, AI-image detection, and KYC/IDV selfie checks.

← Quickstart Retrieve a detection →