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

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 the following steps:

  • Submit the Video for Detection (multipart upload)
  • Query the Job to Retrieve Results

1. Submit the Video for Detection

Upload a video file directly to the API. The server will validate the file.

Supported File Formats

MP4, MOV, AVI, MKV, WEBM

File Size Limits

  • Minimum file size: 1KB
  • Maximum file size: 10MB
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'

Optional Parameters

  • document_type: Type of document (default: 'Video')
  • email: Optional email address for processing

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 score in [0.0, 1.0] 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: ConvNeXt-based classifier 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 CodeMeaning
400Bad Request -- Your request is invalid.
403Forbidden -- The API key is invalid, or there aren't sufficient credits for video processing (0.1 per word).
404Not Found -- The specified resource doesn't exist.
405Method Not Allowed -- You tried to access a resource with an invalid method.
406Not Acceptable -- You requested a format that isn't JSON.
410Gone -- The resource at this endpoint has been removed.
422Invalid Request Body -- Your request body is formatted incorrectly or invalid or has missing parameters.
429Too Many Requests -- You're sending too many requests! Slow it down!
500Internal Server Error -- We had a problem with our server. Try again later.
503Service 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:

  1. Verify your API key is correct
  2. Check if your API key is active in your account
  3. Try regenerating your API key

"Not enough credits" (403)

Cause: Insufficient credits for video processing

Solution:

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

Input Validation Issues

"Unsupported video type" (400)

Cause: File format not supported

Solution:

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

"File size exceeds limit" (400)

Cause: Video file is too large

Solution:

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

"File size is too small" (400)

Cause: Video file is below minimum size requirement

Solution:

  1. Use a larger video file (minimum 1KB)
  2. 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:

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

Processing Issues

Video status "failed"

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

Solution:

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

"User not found"

Cause: Invalid user ID

Solution:

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

"File metadata could not be fetched" (500)

Cause: Unable to access or parse the uploaded file

Solution:

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

Need Help?

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

Contact Us

API Frequently Asked Questions

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

You can get your API key by visiting your account in the TruthScan developer portal. The API key is available at the top of your account page.