> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deeptrack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK

> Integrate deepfake detection into your application in minutes.

> [!NOTE]
>
> 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](https://deeptrack.io) and navigate to **Settings → API Keys**. Your key will begin with `dt_`.

### 2. Install the SDK

```bash Python theme={null}
pip install deeptrack-sdk
```

```bash TypeScript / JavaScript theme={null}
# Coming soon
npm install deeptrack-sdk
```

```bash Java theme={null}
# Coming soon
```

```bash Go theme={null}
# Coming soon
go get github.com/deeptrack/deeptrack-go
```

### 3. Set your API key

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

```bash theme={null}
# .env
DEEPTRACK_API_KEY=dt_your_key_here
```

## Analyze an Image

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

```python Python theme={null}
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"])
```

```typescript TypeScript theme={null}
// 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);
```

```java Java theme={null}
// Coming soon
```

```go Go theme={null}
// Coming soon
```

### Image Result

```json theme={null}
[
  {
    "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.

```python Python theme={null}
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)
```

```typescript TypeScript theme={null}
// 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);
```

```java Java theme={null}
// Coming soon
```

```go Go theme={null}
// Coming soon
```

### Video Result

```json theme={null}
[
  {
    "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

```python Python theme={null}
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']}")
```

```typescript TypeScript theme={null}
// Coming soon
// const usage = await client.usage();
// console.log(usage);
```

```java Java theme={null}
// Coming soon
```

```go Go theme={null}
// Coming soon
```

### Usage Response

```json theme={null}
{
  "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

```python Python theme={null}
analyzer = ImageAnalyzer(client)
results  = analyzer.analyze(path="/path/to/images/")
analyzer.save(results, path="results.csv")
```

```typescript TypeScript theme={null}
// Coming soon
```

```java Java theme={null}
// Coming soon
```

```go Go theme={null}
// Coming soon
```

## Error Handling

```python Python theme={null}
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}")
```

```typescript TypeScript theme={null}
// Coming soon
```

```java Java theme={null}
// Coming soon
```

```go Go theme={null}
// 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](mailto:tech@deeptrack.io)** or reach out to your account manager.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.