# Create User Feedback
Source: https://docs.realitydefender.com/api-reference/endpoint/create_user_feedback

POST api/v2/user-feedback

<ParamField type="string">
  The media result identifier (required). This is the `requestId` returned when a file was processed; you can also obtain it from the [Media Detail](/api-reference/endpoint/get_media_detail) response or the web app when viewing a result.
</ParamField>

<ParamField type="string">
  Your label for the content (required). One of: `REAL`, `SYNTHETIC`, `MANIPULATED`, `UNKNOWN`.
</ParamField>

<ParamField type="string">
  The type of feedback (required). One of: `FALSE_POSITIVE`, `FALSE_NEGATIVE`, `CONFIRMATION`, `OTHER`.
</ParamField>

<ParamField type="string">
  Optional free-text comment. If omitted, no comment is stored.
</ParamField>

Submits user feedback for a completed scan result. The server records who submitted the feedback, links it to the result, and may trigger internal notifications. A successful request returns `201 Created` with the created feedback record.

<Note>
  You may only submit feedback for a result you uploaded, for a result in your same organization, or, for certain roles, on behalf of your organization. If the `requestId` is unknown, the API returns `400`. If you are not allowed to comment on that result, the API returns `403`.
</Note>

### Authorization

You must include the `x-api-key` header in your request. The key must belong to a user with RealScan access to authenticate the request and properly attribute the feedback to the correct user and organization.

### Errors

* **400 Bad Request** — No media result exists for the given `requestId` (`"Media result does not exist!"`).
* **403 Forbidden** — The authenticated user cannot submit feedback for that result (`"You are not authorized to create feedback for this media result!"`).

### Sample request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST \
    'https://api.prd.realitydefender.xyz/api/v2/user-feedback' \
    -H 'X-API-KEY: your-api-key-here' \
    -H 'Content-Type: application/json' \
    -d '{
      "requestId": "your-request-id",
      "label": "REAL",
      "feedbackCategory": "CONFIRMATION",
      "comment": "Looks correct in context."
    }'
  ```

  ```python python theme={null}
  import requests

  url = "https://api.prd.realitydefender.xyz/api/v2/user-feedback"
  headers = {
      "X-API-KEY": "your-api-key-here",
      "Content-Type": "application/json",
  }
  payload = {
      "requestId": "your-request-id",
      "label": "REAL",
      "feedbackCategory": "CONFIRMATION",
      "comment": "Looks correct in context.",
  }
  response = requests.post(url, json=payload, headers=headers)
  print(response.status_code, response.json())
  ```
</CodeGroup>

### Sample response

`201 Created` — body shape is similar to:

```
{
  "id": "uuid",
  "userId": "user-id",
  "requestId": "your-request-id",
  "institutionId": "institution-id",
  "text": "Looks correct in context.",
  "category": "CONFIRMATION",
  "userName": "Jane Doe",
  "userEmail": "jane@example.com",
  "orgName": "Organization name",
  "mediaType": "VIDEO",
  "mediaViewUrl": "https://...",
  "mediaSource": "API",
  "label": "REAL",
  "createdAt": "2025-01-15T12:00:00.000Z"
}
```

Field presence may vary slightly depending on the user profile and the stored result; the `text` field is only populated if a `comment` is included in the request.


# All Media
Source: https://docs.realitydefender.com/api-reference/endpoint/get_all_media

GET api/v2/media/users/pages/{page_number}

<ParamField type="number">
  The number of results to return per page. Default is 10.
</ParamField>

<ParamField type="string">
  Results where the file name matches the input name.
</ParamField>

<ParamField type="string">
  Returns upload data from startDate to now. Use format 'yyyy-mm-dd'.
</ParamField>

<ParamField type="string">
  Returns upload data from startDate (if entered) to endDate. Use format 'yyyy-mm-dd'.
</ParamField>

<ParamField type="string">
  Specifies which page to return when iterating through results.
</ParamField>

Use this endpoint to view the deepfake detection results for all submitted items, including uploaded files and social media URLs.

<Note>
  This endpoint is specific to a given user's uploads. Although organization administrators can view organization-wide uploads, this endpoint will not return organization-wide uploads.
</Note>

### Authorization

You must include the `x-api-key` in your request headers. This key is essential for authenticating your request and ensuring secure access to the API.

### Pagination

By default, if no page is defined, the API will return 100 responses. In order to paginate through responses, you will want to specify a page number in the URL: `/api/v2/media/users/pages/{page-number}`.

### Sample Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.prd.realitydefender.xyz/api/v2/media/users" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json"
  ```

  ```python python theme={null}
  import requests 

  url = "https://api.prd.realitydefender.xyz/api/v2/media/users"
  headers = {
      "X-API-KEY": "your-api-key",
      "Content-Type": "application/json"
  }
  response = requests.get(url, headers=headers).json()
  print(response)

  ```
</CodeGroup>

### Response

The response contains a list of responses for each submitted item. For more detail on how to parse the individual response, please visit our [Media Detail](/api-reference/endpoint/get_media_detail) API documentation.

<Warning>
  We highly recommend that you leverage the ensemble results that are returned rather than building off the individual model results.
</Warning>


# Media Detail
Source: https://docs.realitydefender.com/api-reference/endpoint/get_media_detail

GET api/media/users/{requestId}

<ParamField type="string">
  Returns deepfake detection result for specified requestId.
</ParamField>

This endpoint returns the results for a specific upload. When you upload a file or submit a social media URL, the response of a successful request will contain the `requestId`. You can also find your requestId in the URL path when you access the upload in the web application.

### Authorization

To fetch media detail, you must include the `x-api-key` in your request headers. This key is essential for authenticating your request and ensuring secure access to the API.

### Sample Code Snippet

Here's an example of how you can fetch the results for an uploaded file or social media URL.

<CodeGroup>
  ```bash curl theme={null}
  REQUEST_ID="your-requestId"
  API_KEY="your-api-key"

  curl -X GET \
    "https://api.prd.realitydefender.xyz/api/media/users/${REQUEST_ID}" \
    -H "X-API-KEY: ${API_KEY}" \
    -H "Content-Type: application/json"
  ```

  ```python python theme={null}
  import requests 

  requestId = "your-request-id"
  url = f"https://api.prd.realitydefender.xyz/api/media/users/{requestId}"
  headers = {
      "X-API-KEY": "your-api-key",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers).json()
  print(response.get('filename','N/A'))
  print(response.get('overallStatus','N/A'))


  ```
</CodeGroup>

### Sample Response

```
{
    "filename": "rd-file-name",
    "originalFileName": "original-file-name",
    "requestId": "request-id",
    "uploadedDate": "uploaded-date",
    "mediaType": "media-type", // AUDIO, VIDEO, TEXT, IMAGE
    "socialLink": "social-link", // populated for social media submissions
    "socialLinkDownloaded": true, // populated for social media submissions
    "socialLinkDownloadFailed": false, // populated for social media submissions
    "showAudioResult": "show-audio-result", // True, False
    "audioRequestId": "audio-request-id", // populated if showAudioResult is True
    "userId": "user-id",
    "institutionId": "institution-id",
    "releaseVersion": "2.3.1",
    "overallStatus": "status", // AUTHENTIC, FAKE, SUSPICIOUS, NOT_APPLICABLE, UNABLE_TO_EVALUATE
    "resultsSummary": {
        "status": "status", // AUTHENTIC, FAKE, SUSPICIOUS, NOT_APPLICABLE, UNABLE_TO_EVALUATE
        "metadata": {
            "languages": ["language"], // detected languages include english, spanish, and portuguese
            "finalScore": score // when present, typically > 0 and < 100 (clamped like model finalScore)
        }
    },
    "models": [
        {
            "name": "model-name", // see Possible models; names can change over time
            "data": {
                "score": 0.99,
                "decision": "ARTIFICIAL", // or AUTHENTIC
                "raw_score": 0.99
            },
            "status": "FAKE", // AUTHENTIC, FAKE, SUSPICIOUS, NOT_APPLICABLE, UNABLE_TO_EVALUATE, ANALYZING
            "predictionNumber": 0.99, // raw model score (typically 0–1); may be null
            "normalizedPredictionNumber": 99, // > 0 and < 100 when available; else null
            "rollingAvgNumber": null,
            "finalScore": 99, // > 0 and < 100 when available; else null
            "code": null // e.g. "not_applicable" when status is NOT_APPLICABLE
        }
        // additional model results...
    ],
    "storageLocation": "https://...presigned...",
    "thumbnail": "https://...presigned...", // may be "" when unavailable
    "aggregationResultUrl": "institution-id/request-id.ext/aggregation.json",
    "modelMetadataUrl": "https://...presigned.../aggregation.json",
    "audioModelMetadataUrl": "https://...presigned.../aggregation.json", // combined video+audio only; else ""
    "heatmaps": {
        "model-name": "https://...presigned.../heatmaps/model-name/heatmap.png"
    },
    "explainabilityUrl": "" // text: pre-signed HTML URL; otherwise typically ""
}
```

## Response Schema

### Core fields

| Field              | Type           | Description                                         |
| ------------------ | -------------- | --------------------------------------------------- |
| `filename`         | string         | Display / upload filename                           |
| `originalFileName` | string         | Original uploaded filename                          |
| `requestId`        | string         | ID used to fetch this result                        |
| `uploadedDate`     | string         | Upload timestamp (ISO 8601)                         |
| `mediaType`        | string         | `IMAGE`, `VIDEO`, `AUDIO`, or `TEXT`                |
| `overallStatus`    | string         | Overall media status (see statuses below)           |
| `userId`           | string         | Uploading user ID                                   |
| `institutionId`    | string \| null | Organization ID                                     |
| `releaseVersion`   | string         | Platform release version for the scan               |
| `resultsSummary`   | object         | Ensemble status, score, and optional reasons/errors |
| `models`           | array          | Per-model detection results (see below)             |

### `models[]` object

Each entry in `models` has the following fields:

| Field                        | Type                     | Description                                                                                                                                 |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                       | string                   | Model slug (see [Possible models](#possible-models)). **Model names can change in the future** as detectors are added, renamed, or retired. |
| `status`                     | string                   | Model status (`FAKE`, `AUTHENTIC`, `SUSPICIOUS`, `NOT_APPLICABLE`, `UNABLE_TO_EVALUATE`, `ANALYZING`, …)                                    |
| `predictionNumber`           | number \| null           | Raw model score when available (typically 0–1). Not clamped; can be exactly `0` or `1`.                                                     |
| `normalizedPredictionNumber` | number \| null           | Normalized score when available; always **> 0 and \< 100** (never exactly 0 or 100)                                                         |
| `rollingAvgNumber`           | number \| null           | Rolling average when applicable (same 0–100 normalization/clamping as `normalizedPredictionNumber` when present)                            |
| `finalScore`                 | number \| null           | Final model score when available; always **> 0 and \< 100** (never exactly 0 or 100)                                                        |
| `data`                       | object \| null           | Model-specific payload (for example `decision`, `score`, `raw_score`; shape varies by model)                                                |
| `error`                      | object \| string \| null | Error details when the model failed                                                                                                         |
| `code`                       | string \| null           | Machine-readable code (for example `not_applicable`)                                                                                        |

Missing or in-flight models may appear with `status: "ANALYZING"` and null scores. Models that do not apply to the media type typically return `status: "NOT_APPLICABLE"` with `code: "not_applicable"` and `data: null`.

### Explainability and visualization fields

These fields power the same visualization experience as the Reality Defender UI.

| Field                   | Type   | Media types                            | Description                                                                                                                                                                                                                                                                                                        |
| ----------------------- | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `heatmaps`              | object | **Image** (meaningful)                 | Map of model name → pre-signed PNG URL. Usable heatmaps are only for **artificial image models that are not ensemble** (`models[].status` = `FAKE` / decision `ARTIFICIAL`). The API may still return entries for non-artificial image models, ensemble models, or other media types, but those links are invalid. |
| `explainabilityUrl`     | string | **Text** (populated)                   | Pre-signed URL to HTML explainability output (for example `explainability-rd-llm-txt.html`). Empty string (`""`) for image/video/audio in typical responses.                                                                                                                                                       |
| `thumbnail`             | string | Video (common), Image (when available) | Pre-signed thumbnail URL, or `""` when unavailable                                                                                                                                                                                                                                                                 |
| `storageLocation`       | string | All                                    | Pre-signed URL to the original uploaded media (may be empty if originals were deleted by retention policy)                                                                                                                                                                                                         |
| `aggregationResultUrl`  | string | All                                    | Raw S3 object key for `aggregation.json` (not a downloadable URL)                                                                                                                                                                                                                                                  |
| `modelMetadataUrl`      | string | All                                    | Pre-signed URL for the same `aggregation.json` referenced by `aggregationResultUrl`. Fetch this to build UI-like visualizations.                                                                                                                                                                                   |
| `audioModelMetadataUrl` | string | Combined video+audio                   | Pre-signed URL for the extracted-audio aggregation JSON when `showAudioResult` is true; otherwise `""`                                                                                                                                                                                                             |

#### `aggregationResultUrl` / `modelMetadataUrl` and UI visualization

* `aggregationResultUrl` is the storage key, typically shaped like:
  `{institutionId}/{requestId}{extension}/aggregation.json`
  (for example `.mp4`, `.png`, `.txt`, or an audio extension)
* `modelMetadataUrl` is the browser-readable, pre-signed URL for that file.
* For combined video+audio scans, `audioModelMetadataUrl` points at the extracted-audio aggregation JSON (a separate key/path from the video aggregation).
* The Reality Defender UI loads this JSON to render report detail (bounding boxes, timelines/scenes, audio chunks, text conclusions, and related metadata).
* Approximate contents by media type:
  * **Image**: `bboxes`, `conclusions`, optional `contextResult`
  * **Video**: frame/timeline fields (for example scenes, frames, tubes), `models`, `ensembles`, `conclusions`, optional `contextResult`
  * **Audio**: `chunks`, `languages`, `conclusions`, `models`, `ensembles`, plus audio metadata
  * **Text**: `models`, `ensembles`, `conclusions`

Use `modelMetadataUrl` / `audioModelMetadataUrl` (not `aggregationResultUrl`) when downloading aggregation artifacts from a client.

#### Pre-signed URL expiry

`heatmaps`, `thumbnail`, `storageLocation`, `modelMetadataUrl`, `audioModelMetadataUrl`, and `explainabilityUrl` are pre-signed URLs that expire after **15 minutes** (`X-Amz-Expires=900`).

If a URL returns access denied / expired:

1. Call this media detail endpoint again for the same `requestId`.
2. Use the newly returned pre-signed URLs.

### Possible models

`models[].name` values you may see (depending on media type and release version):

<Note>
  Model names are not a stable contract. Detectors can be added, renamed, or removed over time. Treat the list below as illustrative examples, and always read `models[].name` from the live response rather than hard-coding specific model slugs.
</Note>

**Image:** `rd-cedar-img`, `rd-elm-img`, `rd-oak-img`, `rd-pine-img`, `rd-img-ensemble`, `rd-context-img`

**Video:** `rd-erie-vid`, `rd-tahoe-vid`, `rd-dynamics-vid`, `rd-vid-ensemble`, `rd-context-vid`

**Audio:** `rd-slim-aud`, `rd-everest-aud`, `rd-aud-ensemble`

**Text:** `rd-llm-txt`

The exact set returned for a scan depends on your plan, institution settings, and `releaseVersion`.

## Response Details

#### NOT\_APPLICABLE

Reality Defender will return NOT\_APPLICABLE as a status if the file contains certain characteristics that are known to impact accuracy.
The reason behind the NOT\_APPLICABLE response will be returned as a list in the `metadata` field.

For example, see below for a `resultsSummary` returned for an image that was not applicable.

```
"resultsSummary": {
    "status": "NOT_APPLICABLE",
    "metadata": {
      "reasons": [
        {
          "code": "relevance",
          "message": "no faces detected/faces too small"
        }
      ]
    }
}
```

**Image Reasons** <br />
Possible reasons returned for `NOT_APPLICABLE` are:

* code: relevance
  * message: no faces detected/faces too small

**Video Reasons** <br />
Currently, our video files do not output reasons. For video visualization (timeline / scene detail), use `modelMetadataUrl` instead.

**Audio Reasons** <br />
Possible reasons returned for `NOT_APPLICABLE` are:

* code: duration
  * message: audio too short (\<1.5s)
* code: detected
  * message: dialtone and/or music
* code: cross-talk
  * message: more than one speaker detected
* code: quality
  * audio too noisy
* code: language
  * audio is more likely in  language

#### UNABLE\_TO\_EVALUATE Response

Reality Defender will return UNABLE\_TO\_EVALUATE if an error occurred while processing the file. This is typically caused by timeouts. You can try again, or upload a smaller file.

Here is an example of the `resultsSummary` returned for an image that is unable to be evaluated.

```
"resultsSummary": {
    "status": "UNABLE_TO_EVALUATE",
    "metadata": {},
    "error": {
      "code": "model-error",
      "message": "An error occurred while processing the file. Please try uploading the file again."
    }
}
```


# AWS Presigned URL
Source: https://docs.realitydefender.com/api-reference/endpoint/presigned

POST api/files/aws-presigned

<ParamField type="string">
  The file name of the file you would like to upload, including the file extension.
</ParamField>

Before uploading a file directly to our storage, you'll need to request a pre-signed URL. This URL provides secure, temporary access to upload your file.

### Authorization

To request a pre-signed URL, you must include the `x-api-key` in your request headers. This key is essential for authenticating your request and ensuring secure access to the API.

### Supported File Types

* Images: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
* Audio: `.mp3`, `.wav`, `.m4a`, `.aac`, `.ogg`, `.flac`, `.alac`
* Video: `.mp4`, `.mov`
* Text: `.txt`

### Size Limits

* Text: up to 5MB
* Images: up to 50MB
* Audio: up to 20MB
* Video: up to 250MB

### Filename Restrictions

* Maximum length: 200 characters
* Special characters will be converted to underscores
* Case insensitive

### Sample Code Snippet

Here's an example of how you can request a pre-signed URL and upload a file.

<CodeGroup>
  ```bash curl theme={null}
  # First request to get the presigned URL
  curl -X POST \
    'https://api.prd.realitydefender.xyz/api/files/aws-presigned' \
    -H 'X-API-KEY: your-api-key-here' \
    -H 'Content-Type: application/json' \
    -d '{"fileName": "your-file.mp4"}'

  # Second request to upload the file using the presigned URL
  # Important: The @ prefix is required before the filename when using --data-binary
  # This tells curl to read the file content (works on all platforms: macOS, Linux, Windows)
  # For filenames with spaces or special characters, wrap the entire @filename in quotes
  curl -X PUT \
    'presigned-url-from-previous-response' \
    --data-binary '@your-file.mp4'

  # Example with a filename containing spaces:
  # curl -X PUT 'presigned-url-from-previous-response' \
  #   --data-binary '@filename with spaces.mp4'
  ```

  ```python python theme={null}
  import requests 

  file_path = "your-file.mp4"
  url = "https://api.prd.realitydefender.xyz/api/files/aws-presigned"
  payload = {
      "fileName": file_path
  }
  headers = {
      "X-API-KEY": "your-api-key-here",
      "Content-Type": "application/json"
  }
  response = requests.post(url, json=payload, headers=headers)  
  response_data = response.json()  
  signed_url = response_data.get("response", {}).get("signedUrl") 
  with open(file_path, 'rb') as file:
      file_data = file.read()
  response = requests.put(signed_url, data=file_data, timeout=20)
  ```
</CodeGroup>


# Social Media URL Upload
Source: https://docs.realitydefender.com/api-reference/endpoint/social

POST api/files/social

<ParamField type="string">
  The social media URL you would like to analyze.
</ParamField>

Use this endpoint to submit a social media link for deepfake detection. The returned response includes a `requestId` that you can use to fetch the analysis result from the media detail endpoint.

### Authorization

To submit a social media URL, you must include the `x-api-key` in your request headers.

### Supported Social Platforms

* Facebook
* Instagram
* Twitter/X
* YouTube
* TikTok
* Threads

### Sample Code Snippet

Here's an example of how you can submit a social media URL and then retrieve the result.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST \
    'https://api.prd.realitydefender.xyz/api/files/social' \
    -H 'X-API-KEY: your-api-key-here' \
    -H 'Content-Type: application/json' \
    -d '{"socialLink": "https://www.youtube.com/watch?v=6O0fySNw-Lw"}'
  ```

  ```python python theme={null}
  import requests

  url = "https://api.prd.realitydefender.xyz/api/files/social"
  payload = {
      "socialLink": "https://www.youtube.com/watch?v=6O0fySNw-Lw"
  }
  headers = {
      "X-API-KEY": "your-api-key-here",
      "Content-Type": "application/json"
  }
  response = requests.post(url, json=payload, headers=headers).json()
  print(response)
  ```
</CodeGroup>


# Quickstart
Source: https://docs.realitydefender.com/api-reference/quickstart

Getting started with our API for deepfake detection

<Warning>
  **Note:** The Reality Defender team now recommends leveraging the [Reality
  Defender SDKs](../sdks/quickstart) for building most integrations. Consider
  checking if your preferred language is included in Reality Defender's suite of
  SDKs.
</Warning>

## Welcome

It's easy to get started with the Reality Defender API. With a couple simple lines of code, you can upload files or submit social media URLs to Reality Defender!

## Authentication

The Reality Defender API uses a secure and straightforward authentication mechanism via the X-API-KEY header.
Every API request must include your unique API key in this header to authenticate and authorize your access to the platform's features and resources.

You will need access to the Reality Defender web platform to generate an API key.
Navigate to our [API key settings](https://app.realitydefender.ai/settings/manage-api-keys) to create a key.

<Note>
  API keys are linked to a user. Organization administrators can view uploads
  from all users, but only uploads for a given user show up by default in the
  [Dashboard](https://app.realitydefender.ai/dashboard).
</Note>

## Request a signed URL

You must request a signed URL to which you will upload your file.

<CodeGroup>
  ```curl curl theme={null}
  curl --location 'https://api.prd.realitydefender.xyz/api/files/aws-presigned' \
  --header 'X-API-KEY: your-api-key-here' \
  --header 'Content-Type: application/json' \
  --data '{
      "fileName": "your-file-path-here"
  }'
  ```

  ```python python theme={null}
  import requests

  file_path = "your-file-path-here"
  url = "https://api.prd.realitydefender.xyz/api/files/aws-presigned"
  payload = {
      "fileName": file_path
  }
  headers = {
      "X-API-KEY": "your-api-key-here",
      "Content-Type": "application/json"
  }
  response = requests.post(url, json=payload, headers=headers)
  signed_url = response.json().get("response", {}).get("signedUrl")
  print(signed_url)
  ```
</CodeGroup>

## Upload a file to the signed URL

Next, upload a file to the signed URL that you received in the prior step.

<Tip>
  When uploading the file, you should only pass in the file itself. You do not
  need to include any other headers or metadata.
</Tip>

<CodeGroup>
  ```curl curl theme={null}
  # The @ prefix is required to upload the file content (works on all platforms: macOS, Linux, Windows)
  # For filenames with spaces or special characters, wrap the entire @filename in quotes
  curl --location --request PUT "your-signed-url-here" \
  --data-binary '@your-file.mp4'
  ```

  ```python python theme={null}
  import requests

  file_path = "your-file-path-here"
  signed_url = "your-signed-url-here"
  with open(file_path, 'rb') as file:
          file_data = file.read()
  response = requests.put(signed_url, data=file_data, timeout=20)
  print(response)
  ```
</CodeGroup>

## Submit a social media URL

Alternatively, instead of uploading a file, you can submit a social media URL for analysis. Send the URL to the social upload endpoint, then continue with [Request a result](#request-a-result) below using the returned `requestId`.

Supported social platforms include Facebook, Instagram, Twitter/X, YouTube, TikTok, and Threads.

<CodeGroup>
  ```curl curl theme={null}
  curl --location 'https://api.prd.realitydefender.xyz/api/files/social' \
  --header 'X-API-KEY: your-api-key-here' \
  --header 'Content-Type: application/json' \
  --data '{
      "socialLink": "https://www.youtube.com/watch?v=6O0fySNw-Lw"
  }'
  ```

  ```python python theme={null}
  import requests

  url = "https://api.prd.realitydefender.xyz/api/files/social"
  payload = {
      "socialLink": "https://www.youtube.com/watch?v=6O0fySNw-Lw"
  }
  headers = {
      "X-API-KEY": "your-api-key-here",
      "Content-Type": "application/json"
  }
  response = requests.post(url, json=payload, headers=headers).json()
  print(response)
  ```
</CodeGroup>

## Request a result

Now that you've uploaded a file or submitted a social media URL, you can request a result. You will need the request ID returned from the prior step.

<Warning>
  Larger files may take longer to analyze. You need to poll the API until the
  results returns, or set up a webhook.
</Warning>

<CodeGroup>
  ```curl curl theme={null}
  curl --location 'https://api.prd.realitydefender.xyz/api/media/users/{request_id}' \
  --header 'X-API-KEY: your-api-key-here' \
  --header 'Content-Type: application/json'
  ```

  ```python python theme={null}
  import requests

  url = "https://api.prd.realitydefender.xyz/api/media/users/{request_id}"
  headers = {
      "X-API-KEY": "your-api-key-here",
      "Content-Type": "application/json"
  }
  response = requests.get(url, headers=headers).json()
  print(response)
  ```
</CodeGroup>

## Interpreting the results

The Reality Defender API returns a lot of detailed information about our deepfake detection results. However, it's recommended to focus specifically on the ensemble results. View our [Media Detail](api-reference/endpoint/get_media_detail) documentation for more detail, including results from both file uploads and social media URL submissions.


# Introduction
Source: https://docs.realitydefender.com/introduction

Welcome to Reality Defender's Documentation Portal

This documentation is designed to guide you through the platform's features, integration processes, and best practices for leveraging Reality Defender to safeguard your organization. Whether you're a developer integrating our API, a content moderator, or an organization aiming to uphold content integrity, you'll find the resources you need to get started.

## Our Product Offerings

Explore our multiple offerings and deployment options that best fit your needs.

<CardGroup>
  <Card title="SDKs" icon="sparkle" href="/sdks/quickstart">
    Easily integrate deepfake detection into your app with the Reality Defender SDK.
  </Card>

  <Card title="Platform REST API" icon="code" href="/api-reference/quickstart">
    REST API for Reality Defender<br />(SDKs are recommended for most cases).
  </Card>

  <Card title="Web Conferencing" icon="desktop" href="https://www.realitydefender.com/real-time-video-deepfake-detection">
    Protect your employees from real-time deepfake threats.
  </Card>

  <Card title="Contact Center" icon="phone" href="https://www.realitydefender.com/solutions/contact-centers">
    Explore our solutions for preventing audio deepfake fraud in contact centers.
  </Card>

  <Card title="Access Security & Fraud Prevention" icon="lock" href="https://www.realitydefender.com/solutions/access-security-fraud-prevention">
    Stop fraudsters using AI to open new accounts or manipulate existing ones.
  </Card>

  <Card title="Brand Safety" icon="stars" href="https://www.realitydefender.com/solutions/brand-monitoring">
    Scan social media content for potential deepfakes.
  </Card>
</CardGroup>


# Reality Defender SDK
Source: https://docs.realitydefender.com/sdks/quickstart

The Reality Defender SDK provides tools and libraries for detecting deepfakes and manipulated media through the Reality Defender API. This SDK is available in multiple programming languages to fit your development needs.

## Overview

The Reality Defender SDK allows you to integrate powerful AI-based deepfake detection capabilities into your applications. With this SDK, you can:

* Upload media files for deepfake and manipulation analysis
* Submit social media URLs for deepfake and manipulation analysis
* Receive detailed results about the authenticity of media
* Get model-specific confidence scores and detection results
* Integrate via event-based or polling approaches
* Process multiple files concurrently with configurable concurrency limits
* Handle image, video, audio, text files, and social media URLs with optimized processing
* Submit user scan feedback for completed results

## Available SDKs

SDK implementations are available for multiple programming languages:

* [TypeScript/JavaScript SDK](https://github.com/Reality-Defender/realitydefender-sdk-typescript) - For web and Node.js applications
* [Python SDK](https://github.com/Reality-Defender/realitydefender-sdk-python) - For Python applications and data science workflows
* [Go SDK](https://github.com/Reality-Defender/realitydefender-sdk-go) - For Go applications
* [Rust SDK](https://github.com/Reality-Defender/realitydefender-sdk-rust) - For Rust applications
* [Java SDK](https://github.com/Reality-Defender/realitydefender-sdk-java) - For Java applications

## Getting Started

1. Obtain an API key from the [Reality Defender Platform](https://app.realitydefender.ai)
2. Choose the SDK for your preferred programming language
3. Follow the installation and usage instructions in the language-specific README

## Analyze Media Files and Social Media Links

Every SDK can analyze either a local media file or a social media URL. In both cases the SDK submits the media to Reality Defender, returns a `requestId`, and then uses that `requestId` to retrieve the analysis result — the same flow regardless of the input. Each language-specific README documents installation, supported social platforms, and usage.

For complete, runnable examples in each language, see:

| Language   | Media file upload                                                                                                                                                                     | Social media URL                                                                                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TypeScript | [`examples/basic.ts`](https://github.com/Reality-Defender/realitydefender-sdk-typescript/blob/main/examples/basic.ts)                                                                 | [`examples/social_media.ts`](https://github.com/Reality-Defender/realitydefender-sdk-typescript/blob/main/examples/social_media.ts)                                                     |
| Python     | [`examples/basic_usage.py`](https://github.com/Reality-Defender/realitydefender-sdk-python/blob/main/examples/basic_usage.py)                                                         | [`examples/social_media.py`](https://github.com/Reality-Defender/realitydefender-sdk-python/blob/main/examples/social_media.py)                                                         |
| Go         | [`examples/basic/main.go`](https://github.com/Reality-Defender/realitydefender-sdk-go/blob/main/examples/basic/main.go)                                                               | [`examples/social/main.go`](https://github.com/Reality-Defender/realitydefender-sdk-go/blob/main/examples/social/main.go)                                                               |
| Rust       | [`examples/basic.rs`](https://github.com/Reality-Defender/realitydefender-sdk-rust/blob/main/examples/basic.rs)                                                                       | [`examples/social_media.rs`](https://github.com/Reality-Defender/realitydefender-sdk-rust/blob/main/examples/social_media.rs)                                                           |
| Java       | [`SimpleFileDetectionExample.java`](https://github.com/Reality-Defender/realitydefender-sdk-java/blob/main/src/main/java/ai/realitydefender/examples/SimpleFileDetectionExample.java) | [`SocialMediaDetectionExample.java`](https://github.com/Reality-Defender/realitydefender-sdk-java/blob/main/src/main/java/ai/realitydefender/examples/SocialMediaDetectionExample.java) |

## Supported Local File Types

* Images: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
* Audio: `.mp3`, `.wav`, `.m4a`, `.aac`, `.ogg`, `.flac`, `.alac`
* Video: `.mp4`, `.mov`
* Text: `.txt`

Note: The free tier only supports uploading audio and image files.

## Size Limits

* Text: up to 5MB
* Images: up to 10MB
* Audio: up to 20MB
* Video: up to 250MB

## Architecture

The SDKs follow a consistent architecture across all language implementations:

* **Client Layer**: Handles HTTP communication with the Reality Defender API
* **Core**: Manages configuration, constants, and event handling
* **Detection**: Processes media uploads, social media URL submissions, and results
* **Types/Models**: Defines data structures for API responses and SDK interfaces
* **Utils**: Provides file operations and helper functions

## Key Features

* **Cross-language compatibility**: Consistent patterns across TypeScript, Python, Go, Rust, and Java
* **Async/Sync support**: Both asynchronous and synchronous programming models
* **Score normalization**: All scores are normalized to a 0-1 range (0.0 to 1.0)
* **Resource management**: Proper cleanup of resources to prevent leaks
* **Flexible integration**: Event-based or polling-based approaches
* **Batch processing**: Process multiple files concurrently with optimized performance
* **Media type support**: Handle audio, image, video, text files, and social media URLs with appropriate processing strategies
* **User feedback**: Record a label and feedback category (`REAL` / `SYNTHETIC` / … and `FALSE_POSITIVE` / `CONFIRMATION` / …) against a completed detection’s **`requestId`**
* **Heatmaps**: `getResult` includes a `heatmaps` map (model name → pre-signed PNG URL) for image scans when a **non-ensemble** model is artificial (`MANIPULATED` in the SDK result; API `FAKE` / UI ARTIFICIAL). Ensemble models and authentic/non-artificial models are omitted. For video, audio, and text, `heatmaps` is `null`. These URLs expire after 15 minutes — re-fetch the result to refresh them. For other media-detail fields (aggregation metadata, explainability, thumbnails, etc.), see [Media Detail](/api-reference/endpoint/get_media_detail).

## Support

For questions, issues, or feature requests, please file an issue in this repository or contact [support@realitydefender.com](mailto:support@realitydefender.com)