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-sdkTypeScript / 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 Python
TypeScript / JavaScript
Java
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 = "folder/photo.jpg" ) print (results) # entire directory results = analyzer.analyze( path = "/path/to/images/" ) for r in results: print (r[ "file" ], r[ "verdict" ], r[ "confidence" ])
Image Result [ { "file" : "photo.jpg" , "verdict" : "FAKE" , "confidence" : 87.3 , "fake_prob" : 0.873 , "warning" : null , "error" : null } ]
Field Type Description filestring Filename verdictstring REAL, FAKE, or UNCERTAINconfidencefloat Confidence percentage (0–100) fake_probfloat Raw fake probability (0.0–1.0) warningstring | null Quality warning if applicable errorstring | 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)
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 filestring Filename verdictstring REAL, FAKE, or UNCERTAINconfidencefloat Confidence percentage (0–100) fake_probfloat Raw fake probability (0.0–1.0) face_pctfloat % of frames with a detected face total_framesint Total frames processed n_segmentsint Number of rPPG segments analyzed segmentsarray Per-segment breakdown errorstring | 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' ] } " )
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" )
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 } " )
Exception Reference Exception Trigger AuthenticationErrorInvalid or missing API key RateLimitErrorMonthly scan limit exceeded FileTooLargeErrorFile exceeds size limit UnsupportedFileErrorFile type not supported JobTimeoutErrorVideo job exceeded max wait time JobFailedErrorServer-side analysis failure APIErrorUnexpected API error DeepTrackErrorBase 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, .gifVideo .mp4, .mov, .avi, .mkvAudio .mp3, .wav, .m4a, .aac, .ogg, .flac
Support For questions or issues, contact support@deeptrack.io 