# Reality Defender

> Detect deepfakes and synthetic media in images, audio, video, and documents. Upload files for analysis and retrieve detection results with confidence scores.

Source: https://cotera.co/docs/reference/tools/individual-tools/reality-defender

---

**Authentication Type:** API Key

**Description:** Detect deepfakes and synthetic media in images, audio, video, and documents. Upload files for analysis and retrieve detection results with confidence scores.

> **Beta Tool:** Please contact support to get this Beta tool added to your account.

***

## Authentication

To authenticate, you'll need a Reality Defender API key from [Reality Defender](https://docs.realitydefender.com/api-reference/quickstart).

Use the `x-api-key` header for authentication.

***

## File Upload

### Get Presigned URL

Get a pre-signed AWS S3 URL for uploading files before analysis.

**Operation Type:** Query (Read)

**Parameters:**

* **fileName** `string` (required): The file name including extension

**Supported File Types:**

* **Documents:** `.pdf`, `.doc`, `.docx`, `.txt` (up to 5MB)
* **Images:** `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp` (up to 10MB)
* **Audio:** `.mp3`, `.wav`, `.m4a`, `.aac`, `.ogg`, `.flac`, `.alac` (up to 20MB)
* **Video:** `.mp4`, `.mov` (up to 250MB)

**Returns:**

* **presigned\_url** `string`: Temporary URL for uploading the file via PUT request

**Example Usage:**

```json
{
  "fileName": "interview_recording.mp3"
}
```

***

## Media Analysis

### List All Media

List all uploaded media with optional filtering and pagination.

**Operation Type:** Query (Read)

**Parameters:**

* **page\_number** `string` (required): Page number for pagination
* **size** `number` (optional, default: 10): Number of results per page
* **name** `string` (optional): Filter by file name
* **startDate** `string` (optional): Filter from date (format: yyyy-mm-dd)
* **endDate** `string` (optional): Filter to date (format: yyyy-mm-dd)

**Returns:**

* **results** `array`: List of media items with detection status and scores

**Example Usage:**

```json
{
  "page_number": "1",
  "size": 25,
  "startDate": "2024-01-01"
}
```

### Get Media Detail

Retrieve deepfake detection results for a previously uploaded file. Analysis is asynchronous: if `status` is `PROCESSING` (`isComplete` false), call this tool again later with the same `requestId`.

**Operation Type:** Query (Read)

**Parameters:**

* **requestId** `string` (required): Unique request identifier from upload

**Returns:**

* **filename** `string | null`: The processed filename
* **originalFileName** `string | null`: The original uploaded filename
* **requestId** `string`: The request ID
* **uploadedDate** `string | null`: When the file was uploaded
* **mediaType** `"AUDIO" | "VIDEO" | "TEXT" | "IMAGE" | null`: The type of media analyzed
* **status** `"AUTHENTIC" | "FAKE" | "SUSPICIOUS" | "NOT_APPLICABLE" | "UNABLE_TO_EVALUATE" | "PROCESSING" | null`: Detection result:
  * `AUTHENTIC` — media is real
  * `FAKE` — AI-generated or manipulated
  * `SUSPICIOUS` — uncertain; manual review recommended
  * `NOT_APPLICABLE` — file characteristics impact accuracy (see `reasonCode`)
  * `UNABLE_TO_EVALUATE` — processing error; re-upload to retry
  * `PROCESSING` — analysis still running; call again later with the same `requestId`
* **finalScore** `number | null`: Ensemble score from 0–100 (higher = more likely to be fake). Null while analysis is still running.
* **metadata** `object | null`: Additional metadata including detected languages
* **models** `array`: Individual model detection results, each with `name` (string), `score` (number | null), and `status` (string | null)
* **reasonCode** `string | null`: Reason code when status is `NOT_APPLICABLE` (relevance, duration, detected, cross-talk, quality, language)
* **isComplete** `boolean`: False while analysis is still running (status `PROCESSING`). When false, call this tool again later with the same `requestId`.
* **message** `string | null`: Guidance on what to do next when there is no usable verdict (still processing, or unable to evaluate). Null otherwise.

**Behavior notes:** An in-progress analysis is returned as a successful result, not an error. Upstream Reality Defender may report `ANALYZING` or omit status entirely early on; the tool normalizes all of these to `PROCESSING`. While `PROCESSING`, poll again with the same `requestId` — larger audio and video files take longer. On `UNABLE_TO_EVALUATE`, the `message` field advises re-uploading the file rather than re-polling.

**Example Usage:**

Request:

```json
{
  "requestId": "req_abc123xyz"
}
```

First response (still processing):

```json
{
  "filename": "interview_recording.mp3",
  "originalFileName": "interview_recording.mp3",
  "requestId": "req_abc123xyz",
  "uploadedDate": "2024-06-15T10:30:00Z",
  "mediaType": "AUDIO",
  "status": "PROCESSING",
  "finalScore": null,
  "metadata": null,
  "models": [],
  "reasonCode": null,
  "isComplete": false,
  "message": "Reality Defender is still analyzing this media. This is not an error. Call this tool again later with the same requestId; larger audio and video files take longer."
}
```

Later poll with the same `requestId` — final verdict:

```json
{
  "filename": "interview_recording.mp3",
  "originalFileName": "interview_recording.mp3",
  "requestId": "req_abc123xyz",
  "uploadedDate": "2024-06-15T10:30:00Z",
  "mediaType": "AUDIO",
  "status": "AUTHENTIC",
  "finalScore": 12,
  "metadata": { "detectedLanguages": ["en"] },
  "models": [
    { "name": "voice-authenticity", "score": 10, "status": "AUTHENTIC" },
    { "name": "spectral-analysis", "score": 14, "status": "AUTHENTIC" }
  ],
  "reasonCode": null,
  "isComplete": true,
  "message": null
}
```

***

## Common Use Cases

**Content Verification:**

* Verify authenticity of user-submitted media
* Screen uploaded content for synthetic manipulation
* Validate identity verification documents

**News & Media:**

* Authenticate video and audio before publication
* Detect AI-generated images in submissions
* Verify source material for investigations

**Security & Compliance:**

* Screen voice recordings for synthetic audio
* Verify video calls and recordings
* Detect manipulated documents and PDFs

**Trust & Safety:**

* Prevent synthetic media from spreading on platforms
* Protect users from deepfake impersonation
* Maintain content integrity standards