SDK - Deeptrack

The deeptrack SDK is the recommended integration method for most use cases. It handles authentication, file uploads, job polling, and error handling automatically — so you can focus on building your product.

Overview

With the deeptrack SDK you can:

Analyze image and video files for deepfake manipulation
Get model-specific confidence scores and verdicts
Handle errors with typed exceptions
Check monthly usage and remaining quota
Export results to CSV

Available SDKs

Language	Status	Install
Python	Available	`pip install deeptrack-sdk`
TypeScript / JavaScript	Coming soon	—
Java	Coming soon	—
Go	Coming soon	—

Getting Started

1. Get an API Key

Log into the deeptrack Dashboard and navigate to Settings → API Keys. Your key will begin with dt_.

2. Install the SDK

pip install deeptrack-sdk

# Coming soon
npm install deeptrack-sdk

# Coming soon

# Coming soon
go get github.com/deeptrack/deeptrack-go

3. Set your API key

Store your key in an environment variable — never hardcode it.

# .env
DEEPTRACK_API_KEY=dt_your_key_here

Analyze an Image

Analyze a single image or an entire directory of images for deepfake manipulation.

import os
from deeptrack import Client
from deeptrack.image import ImageAnalyzer
from dotenv import load_dotenv

load_dotenv()

client   = Client(api_key=os.getenv("DEEPTRACK_API_KEY"))
analyzer = ImageAnalyzer(client)

# single image
results = analyzer.analyze(path="photo.jpg")
print(results)

# entire directory
results = analyzer.analyze(path="/path/to/images/")
for r in results:
    print(r["file"], r["verdict"], r["confidence"])

// Coming soon
// import { Client, ImageAnalyzer } from "deeptrack-sdk";
//
// const client   = new Client({ apiKey: process.env.DEEPTRACK_API_KEY });
// const analyzer = new ImageAnalyzer(client);
// const results  = await analyzer.analyze({ path: "photo.jpg" });
// console.log(results);

// Coming soon

// Coming soon

Image Result

[
  {
    "file":       "photo.jpg",
    "verdict":    "FAKE",
    "confidence": 87.3,
    "fake_prob":  0.873,
    "warning":    null,
    "error":      null
  }
]

Field	Type	Description
`file`	string	Filename
`verdict`	string	`REAL`, `FAKE`, or `UNCERTAIN`
`confidence`	float	Confidence percentage (0–100)
`fake_prob`	float	Raw fake probability (0.0–1.0)
`warning`	string \| null	Quality warning if applicable
`error`	string \| null	Error message if analysis failed

Analyze a Video

Upload a video and wait for the analysis result. The SDK handles the upload and polling loop automatically — no manual polling required.

import os
from deeptrack import Client
from deeptrack.video import VideoAnalyzer
from dotenv import load_dotenv

load_dotenv()

client   = Client(api_key=os.getenv("DEEPTRACK_API_KEY"))
analyzer = VideoAnalyzer(client)

results = analyzer.analyze(path="clip.mp4")
print(results)

// Coming soon
// import { Client, VideoAnalyzer } from "deeptrack-sdk";
//
// const client   = new Client({ apiKey: process.env.DEEPTRACK_API_KEY });
// const analyzer = new VideoAnalyzer(client);
// const results  = await analyzer.analyze({ path: "clip.mp4" });
// console.log(results);

// Coming soon

// Coming soon

Video Result

[
  {
    "file":          "clip.mp4",
    "verdict":       "FAKE",
    "confidence":    91.2,
    "fake_prob":     0.912,
    "face_pct":      98.0,
    "total_frames":  240,
    "n_segments":    4,
    "segments": [
      {
        "segment":    1,
        "start_sec":  0.0,
        "end_sec":    4.3,
        "label":      "FAKE",
        "confidence": 91.2,
        "fake_prob":  0.912
      }
    ],
    "error": null
  }
]

Field	Type	Description
`file`	string	Filename
`verdict`	string	`REAL`, `FAKE`, or `UNCERTAIN`
`confidence`	float	Confidence percentage (0–100)
`fake_prob`	float	Raw fake probability (0.0–1.0)
`face_pct`	float	% of frames with a detected face
`total_frames`	int	Total frames processed
`n_segments`	int	Number of rPPG segments analyzed
`segments`	array	Per-segment breakdown
`error`	string \| null	Error message if analysis failed

Check Usage

usage = client.usage()
print(f"Plan:      {usage['plan']}")
print(f"Used:      {usage['used_this_month']} / {usage['monthly_limit']}")
print(f"Remaining: {usage['remaining']}")
print(f"Resets:    {usage['resets_at']}")

// Coming soon
// const usage = await client.usage();
// console.log(usage);

// Coming soon

// Coming soon

Usage Response

{
  "owner":           "Gotham Media",
  "track":           "api",
  "plan":            "starter",
  "rate_per_scan":   0.39,
  "monthly_limit":   5000,
  "used_this_month": 23,
  "remaining":       4977,
  "resets_at":       "2026-03-31"
}

Save Results to CSV

analyzer = ImageAnalyzer(client)
results  = analyzer.analyze(path="/path/to/images/")
analyzer.save(results, path="results.csv")

// Coming soon

// Coming soon

// Coming soon

Error Handling

from deeptrack import (
    Client,
    AuthenticationError,
    RateLimitError,
    FileTooLargeError,
    UnsupportedFileError,
    JobTimeoutError,
    DeeptrackError,
)
from deeptrack.video import VideoAnalyzer

client   = Client(api_key=os.getenv("DEEPTRACK_API_KEY"))
analyzer = VideoAnalyzer(client)

try:
    results = analyzer.analyze(path="clip.mp4")
except AuthenticationError:
    print("Invalid or missing API key.")
except RateLimitError as e:
    print(f"Monthly limit exceeded: {e}")
except FileTooLargeError:
    print("File exceeds the 500MB video limit.")
except UnsupportedFileError as e:
    print(f"Unsupported file type: {e}")
except JobTimeoutError:
    print("Analysis timed out — try a shorter clip.")
except DeeptrackError as e:
    print(f"deeptrack error: {e}")

// Coming soon

// Coming soon

// Coming soon

Exception Reference

Exception	Trigger
`AuthenticationError`	Invalid or missing API key
`RateLimitError`	Monthly scan limit exceeded
`FileTooLargeError`	File exceeds size limit
`UnsupportedFileError`	File type not supported
`JobTimeoutError`	Video job exceeded max wait time
`JobFailedError`	Server-side analysis failure
`APIError`	Unexpected API error
`DeeptrackError`	Base class for all SDK exceptions

Size Limits

Media Type	Maximum Size
Image	15 MB
Video	500 MB
Audio	50 MB

Supported File Types

Type	Extensions
Image	`.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`
Video	`.mp4`, `.mov`, `.avi`, `.mkv`
Audio	`.mp3`, `.wav`, `.m4a`, `.aac`, `.ogg`, `.flac`

Support

For questions or issues, email tech@deeptrack.io or reach out to your account manager.

​Overview

​Available SDKs

​Getting Started

​1. Get an API Key

​2. Install the SDK

​3. Set your API key

​Analyze an Image

​Image Result

​Analyze a Video

​Video Result

​Check Usage

​Usage Response

​Save Results to CSV

​Error Handling

​Exception Reference

​Size Limits

​Supported File Types

​Support

Overview

Available SDKs

Getting Started

1. Get an API Key

2. Install the SDK

3. Set your API key

Analyze an Image

Image Result

Analyze a Video

Video Result

Check Usage

Usage Response

Save Results to CSV

Error Handling

Exception Reference

Size Limits

Supported File Types

Support