The Copyleaks AI Video Detection API, part of the Copyleaks AI Detector, analyzes whether a video was generated or partially generated by AI. The API is asynchronous, you submit a video URL, and Copyleaks notifies your server via webhook when the results are ready. This guide walks through submitting a video for AI detection and interpreting the webhook response.
Just want to try it? Open the Video Detection Playground to submit a sample video and inspect the webhook response in your browser, no code required.

Get started

1

Before you begin

Before you start, ensure you have the following:
2

Installation

Choose your preferred method for making API calls.
HTTP needs no installation - call the API with any standard HTTP client, or import our Postman collection for a quicker start.
3

Login

To perform a scan, we first need to generate an access token. For that, we will use the login endpoint. The API key can be found on the Copyleaks API Dashboard.Upon successful authentication, you will receive a token that must be attached to subsequent API calls via the Authorization: Bearer <TOKEN> header. This token remains valid for 48 hours.
Response
Save this token! It’s valid for 48 hours and can be reused for subsequent API calls.
4

Submit a video for analysis

Use the AI Video Detector endpoint to submit a video URL for analysis. Provide a unique scanId for each submission and a webhook URL to receive the results.
This API is asynchronous. The submission returns 201 Created immediately, and the detection results are sent to your webhook URL once processing completes.

Providing a video URL

The API requires a publicly accessible URL pointing to your video file - Copyleaks will fetch it directly. The video must be reachable at the time of processing, so avoid URLs that expire before the scan completes.A common approach is to upload the video to cloud storage and generate a pre-signed URL:
  • Amazon S3 - Upload the file to an S3 bucket and generate a pre-signed URL with a sufficient expiry window (e.g. 1 hour). The bucket does not need to be public.
  • Google Cloud Storage - Upload to a GCS bucket and create a signed URL using the GCS console or SDK.
  • Azure Blob Storage - Upload to a container and generate a SAS URL with read access.
  • Any CDN or file host - Any URL that returns the raw video file with a Content-Type video header works.
If your video is hosted behind authentication (e.g. a signed URL that also requires a token header, or an internal storage service), use the top-level headers field in the request body to pass the necessary HTTP headers. Copyleaks will include these headers when fetching the video.For example, to pass a bearer token:
Each entry in the array is a ["Header-Name", "Header-Value"] pair. You can include multiple headers by adding more pairs to the array.

Setting up your webhook

The webhooks.url field is where Copyleaks will POST the detection results when processing is done. This must be a publicly reachable HTTPS endpoint on your server.A few tips for getting started:
  • During development - Use a tool like ngrok or webhook.site to expose a local server or inspect incoming payloads without writing any backend code.
  • In production - Implement a route in your API (e.g. POST /webhook/video-results) that receives the payload, validates it, and stores or acts on the results.
  • Security - Use the optional webhooks.headers field to pass a secret token with the webhook request, which your server can verify to ensure the request is coming from Copyleaks.

Video requirements

Returned as 400 Bad Request at submit (synchronous):
  • Missing or invalid scanId, filename, url, model, or webhooks
  • Unsupported file extension (supported: .mp4, .avi, .mov, .mkv, .webm, .flv, .wmv, .mpg, .m4v, .3gp, .mxf)
  • Filename longer than 255 characters
  • Invalid verb value
Delivered to your webhook as an error result (asynchronous):
  • Duration outside 2 seconds-1 hour → video_too_short (67) / video_too_long (68)
  • File larger than 512 MiB → file_too_large (6)
  • Resolution below 360×360 → video_resolution_too_low (65)
  • Frame rate below 16 FPS → fps_too_low (66)
  • Undecodable codec → unsupported_video_codec (71)
  • Corrupt or truncated file → video_truncated (70)
  • Generic decode failure → video_load_failed (72)
For testing, set "sandbox": true. Sandbox mode is free and returns mock results.
5

Receive the webhook result

Once Copyleaks finishes analyzing the video, it sends a POST request to your webhook URL with the detection results.

Example webhook payload

Understanding the results

The webhook response contains three key sections:audioResult and visualResult - Time-based detections for the audio and visual tracks, encoded as arrays of start positions (starts) and durations (lengths) in milliseconds.The exclude object within each result identifies segments that were not scored. These ranges are excluded because the content could not be meaningfully analyzed, and they are not counted in the AI ratio calculations.summary - Overall AI ratios. Segments listed in exclude are not counted in any of these calculations:
  • audioAIRatio - Ratio of AI-detected audio duration to total audible duration. Excluded audio ranges are not counted (0.0-1.0).
  • visualAIRatio - Ratio of AI-detected visual duration to total visible duration. Excluded visual ranges are not counted (0.0-1.0).
  • overallAIRatio - Combined AI ratio across both audio and visual tracks, relative to the total video duration (0.0-1.0).
videoInfo - Video duration and optional C2PA/embedded metadata identifying the generating tool.For a complete breakdown of all response fields, see the AI Video Detection Response documentation.
6

You’re done

You’ve successfully submitted a video for AI detection and received the webhook results. You can now use summary.overallAIRatio and the time-based audioResult / visualResult data in your application.

Next steps

API Reference

The complete reference for the AI Video Detection endpoint.

AI Video Detection Response

The complete webhook response structure.

AI Image Detection Guide

Detect AI-generated images using the synchronous image detection API.