API Documentation

AI Video Detection API

Complete documentation for integrating TruthScan's AI video detection API into your applications.

Try it out without code by visiting our FastAPI endpoint: https://detect-video.truthscan.com/docs

Pricing & credits

Each video detection request consumes credits from your account when processing completes.

Check your balance with GET /check-user-credits. View pricing plans

Authentication

TruthScan uses API keys to allow access to the API. You can get your API key at the top of the page in our developer portal.

TruthScan expects for the API key to be included in all API requests to the server in a request body that looks like the following:

{
  "key": "YOUR API KEY GOES HERE"
}

You must replace YOUR API KEY GOES HERE with your personal API key.

AI Video Detector

Detect (2-Step Process)

The AI Video Detection workflow consists of two steps:

Submit the video for detection (multipart upload or URL)
Query the job to retrieve results

Detection Models

Select which ML model runs during the detection pipeline using the optional model parameter. If omitted, generic is used.

generic: General-purpose AI video detection model (default)
faceswap: Dedicated Face Swap video detection model

Both models use the same detection pipeline (metadata → watermark → ML) and return the same response format. Invalid model values return 422.

1. Submit the Video

Upload a video file directly to the API, or submit a video URL. The server will validate the file.

Supported File Formats

mp4, mov, avi, mkv, webm

File Size Limits

Minimum file size: 1KB
Maximum file size: 100MB

Submit via file upload

Headers

key (required): Your API key
email: Optional email address
userkey: Optional integration user key

Multipart form-data

file (required): The video to analyze
model: Detection model to use i.e generic or faceswap (optional, default: generic)

POST https://detect-video.truthscan.com/detect-file

Example Request

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

Face Swap model example

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4' \
  -F 'model=faceswap'

Optional Parameters

document_type: Type of document (default: Video)
email: Email address for processing
model: Detection model i.e generic or faceswap (default: generic)

Submit via URL

Headers

Content-Type: application/json

Body (JSON)

key (required): Your API key
url: https://ai-video-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>
model: Detection model to use i.e generic or faceswap (optional, default: generic)

POST https://detect-video.truthscan.com/detect

Example Request

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "generic"
}'

Face Swap model example

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "faceswap"
}'

Optional Parameters

document_type: Type of document (default: Video)
email: Email address for processing
model: Detection model i.e generic or faceswap (default: generic)

Example Response

{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
  "status": "pending"
}

The response includes a unique video ID for tracking the detection status.

2. Query Detection Status and Results

After submitting, poll the /query endpoint with the job id to retrieve status and results.

POST https://detect-video.truthscan.com/query

Example Request

curl -X POST 'https://detect-video.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"id":"JOB-ID-GOES-HERE"}'

Example Response

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

Result Details

status: "pending", "analyzing", "done", or "failed"
result: Scalar AI-likelihood score in [0.0, 1.0] (higher means more likely AI-generated), derived from ML prob_fake
final_stage: Last stage that contributed result: 'metadata', 'watermark', or 'ml'
metadata: Always sets prediction: 'no_detection' and confidence: 0.0. Status can be 'reject', 'reencode', or 'ok'
watermark: Heuristic that samples frames and computes pseudo-confidence from pixel variance
ml: Classifier model run on sampled frames. Returns prob_fake in [0.0, 1.0] and label ('ai_generated' if prob_fake ≥ 0.5, else 'no_detection')
latency_sec: Total pipeline time

The "status" field will be one of: "pending" (processing is queued), "analyzing" (AI detection is in progress), "done" (results are available), or "failed" (processing failed).

Check User Credits

This endpoint accepts the users apikey via the header. And returns users credit details.

GET https://detect-video.truthscan.com/check-user-credits

Example Request

curl -X 'GET' \
  'https://detect-video.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Example Response

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Health Check

Check the health status of the API server.

GET https://detect-video.truthscan.com/health

Example Request

curl -X 'GET' \
  'https://detect-video.truthscan.com/health' \
  -H 'accept: application/json'

Example Response

{
  "status": "healthy"
}

Errors

Most errors will be from incorrect parameters being sent to the API. Double check the parameters of each API call to make sure it's properly formatted, and try running the provided example code.

The generic error codes we use conform to the REST standard:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
403	Forbidden -- The API key is invalid, or there aren't sufficient credits for video processing.
404	Not Found -- The specified resource doesn't exist.
405	Method Not Allowed -- You tried to access a resource with an invalid method.
406	Not Acceptable -- You requested a format that isn't JSON.
410	Gone -- The resource at this endpoint has been removed.
422	Invalid Request Body -- Your request body is formatted incorrectly or invalid or has missing parameters.
429	Too Many Requests -- You're sending too many requests! Slow it down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Common Issues and Solutions

Authentication Issues

"User verification failed" (403)

Cause: Invalid or expired API key

Solution:

Verify your API key is correct
Check if your API key is active in your account
Try regenerating your API key

"Not enough credits" (403)

Cause: Insufficient credits for video processing

Solution:

Check your remaining credits using /check-user-credits
Purchase additional credits if needed

Input Validation Issues

"Unsupported video type" (400)

Cause: File format not supported

Solution:

Convert the video to a supported format (MP4, MOV, AVI, MKV, WEBM)
Ensure the file extension and MIME type are correct

"File size exceeds limit" (400)

Cause: Video file is too large

Solution:

Compress, trim, or re-encode the video to reduce size (maximum 100MB)
Use a more efficient codec/container

"File size is too small" (400)

Cause: Video file is below minimum size requirement

Solution:

Use a larger video file (minimum 1KB)
Check if the file was corrupted during upload

"Invalid file type" (400)

Cause: File type validation failed (e.g., wrong MIME type or corrupted file)

Solution:

Ensure the file is a valid video format
Verify the MIME type matches the file extension
Re-export or re-encode the file if necessary

Invalid model value (422)

Cause: The model parameter is not generic or faceswap

Solution:

Omit model to use the default generic model
Set model to generic for general AI video detection
Set model to faceswap for Face Swap video detection

Processing Issues

Video status "failed"

Cause: Processing failed (e.g., unreadable container, decode errors)

Solution:

Ensure the container/codec is commonly supported (H.264/AAC in MP4 recommended)
Re-encode the video using a standard preset (e.g., ffmpeg) and re-upload
Ensure the file meets size and format requirements
Contact support if the issue persists

"User not found"

Cause: Invalid user ID

Solution:

Verify your API key is correct and tied to an active account
Ensure the integration user is valid and active
Re-authenticate if needed

"File metadata could not be fetched" (500)

Cause: Unable to access or parse the uploaded file

Solution:

Verify the upload completed successfully
Check the file is accessible and not corrupted
Try re-uploading the file

Need Help?

For more information about using our API or for technical support, please contact us.

API Frequently Asked Questions

Find answers to the most common questions about our AI video detection API.