cotera
Logo

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.

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:

{
  "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:

{
  "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:

{
  "requestId": "req_abc123xyz"
}

First response (still processing):

{
  "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:

{
  "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