Quickstart

Note: The Reality Defender team now recommends leveraging the Reality Defender SDKs for building most integrations. Consider checking if your preferred language is included in Reality Defender’s suite of SDKs.

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 to create a key.

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.

Request a signed URL

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

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"
}'

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)

Upload a file to the signed URL

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

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

# 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'

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)

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 below using the returned requestId. Supported social platforms include Facebook, Instagram, Twitter/X, YouTube, TikTok, and Threads.

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"
}'

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)

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.

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

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'

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)

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 documentation for more detail, including results from both file uploads and social media URL submissions.

API Documentation

Endpoint Examples

Welcome

Authentication

Request a signed URL

Upload a file to the signed URL

Request a result

Interpreting the results

​Welcome

​Authentication

​Request a signed URL

​Upload a file to the signed URL

​Submit a social media URL

​Request a result

​Interpreting the results

Welcome

Authentication

Request a signed URL

Upload a file to the signed URL

Submit a social media URL

Request a result

Interpreting the results