The Copyleaks AI Image Detection API is a powerful tool to assess whether a given image was generated or partially generated by an AI. The check endpoint used in this guide is synchronous, meaning you get the results in the same API call. An asynchronous endpoint that delivers results by webhook is also available. This guide will walk you through the process of submitting an image to the Copyleaks AI Detector using multipart/form-data format and understanding the results.

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 is valid for 48 hours and can be reused for subsequent API calls.
4

Submit for analysis

Use the AI Image Detection endpoint to send an image for analysis. We suggest you provide a unique scanId for each submission.This guide uses multipart/form-data format, which sends the image file directly without base64 encoding overhead.
Use multipart/form-data to send a binary image file. Use application/json when you need to submit image data as a base64-encoded string. Note that multipart only accepts binary files, base64-encoded images are not supported for multipart requests.

Image Requirements

  • Size: Minimum 400px on each side, maximum 27 megapixels in total (for example, 6000×4500px)
  • File size: Less than 32MB
  • Formats: PNG, JPG, JPEG, BMP, WebP, HEIC/HEIF

Object Detection (Optional)

To also locate specific objects in the image, add the objectDetection field with the objects to look for. The response then includes a detectedObjects array with one Run-Length Encoded (RLE) segmentation mask per object found, alongside the AI-detection result, for the same 1 credit.
  • At least one entry, maximum 3 entries.
  • Each entry’s object value must be a non-empty string of at most 32 characters.
  • With multipart/form-data, send the list as a JSON-encoded string in a single form field; with application/json, send it as an array.
cURL with objectDetection
For testing, set "sandbox": true. Sandbox mode is free and returns mock results.
5

Interpreting the response

The API response contains:
  • A summary object with the AI score: the share of pixels flagged as AI vs. human
  • A result object with the detection mask, run-length encoded (RLE)
  • imageInfo with the image dimensions and metadata (when available)
  • detectedObjects (only when you sent objectDetection) with one RLE-encoded segmentation mask per object found. Objects that were not found are omitted, so look entries up by object
  • scannedDocument with scan details including credits used

Understanding the Detection Mask

Run-Length Encoding (RLE) is a compression method used to represent the AI-detected regions of the image efficiently. It provides an array of starts positions and lengths for each run of AI-detected pixels in a flattened 1D version of the image.You can decode this RLE data to create a binary mask. Below are implementations in different languages:
The resulting binary mask is an array where a 1 (or true in Java) represents an AI-detected pixel. You can use this mask to create a visual overlay on the original image.

Creating a Visual Overlay

After decoding the RLE data, you can use the resulting mask to draw a semi-transparent overlay on the original image. Here are some examples of how to achieve this:
For a complete breakdown of all fields in the response, see the AI Image Detection Response documentation.
6

Summary

You have successfully submitted an image for AI detection. You can now use the JSON response in your application to take further action based on the findings.

Frequently asked questions

Yes, the check endpoint is synchronous: you send the image and receive the results in the same API call, with no webhook required. If you’d rather submit an image URL and get the results by webhook, use the asynchronous endpoint.
Images must be at least 400px on each side, at most 27 megapixels in total (for example, 6000×4500px), and under 32MB. Supported formats are PNG, JPG, JPEG, BMP, WebP, and HEIC/HEIF. The same limits apply to the synchronous and asynchronous endpoints.
Yes. Use application/json to send a base64-encoded image. The multipart/form-data method shown in this guide accepts only binary files, not base64.
A summary with the AI score (the share of pixels flagged as AI vs. human), a result object with the run-length encoded (RLE) detection mask of AI-detected regions, imageInfo with dimensions and metadata, and scannedDocument with scan details. See the AI Image Detection Response reference.
Decode the detection mask’s RLE runs into a binary mask (one value per pixel), then draw a semi-transparent overlay on the original image. This guide includes ready-to-use decode and overlay code in Python, JavaScript, and Java.

Next steps

API Reference

Explore the full API reference for the AI Image Detection endpoint.

AI Image Detection Response

Explore the full response for the AI Image Detection.

Performance Best Practices

Learn optimization strategies for performance and accuracy with image detection.

Testing Methodology

Learn about the accuracy and testing methodology of the AI Image Detection product.