POST https://api.copyleaks.com/v1/ai-image-detector/{scanId}/check

Detect whether an image is AI-generated or partially AI-generated. Returns a detailed analysis with an RLE mask indicating AI-generated regions.

Authentication Required

You need to login with a user and API key in order to access this method. Add this HTTP header to your request:

Authorization: Bearer < Your-Login-Token >

Rate Limits

Image detection API has a rate limit of 900 requests per 15 minutes per host. If exceeded, requests will be rejected with a 429 status code until the rate limit window resets.

Request

Path Parameters

scanId string Required

A unique scan id provided by you. We recommend you use the same id in your database to represent the scan in the Copyleaks database. This will help you to debug incidents. Using the same ID for the same file will help you to avoid network problems that may lead to multiple scans for the same file. Learn more about the criteria for creating a Scan ID.

>= 3 characters <= 36 characters

Match pattern: [a-z0-9] !@$^&-+%=_(){}<>';:/.",~|

Supported Content Types

Submit images using multipart/form-data (recommended) or JSON with base64.

Performance Tip

multipart/form-data sends the image file directly without base64 encoding overhead, making it more efficient for large images. Use application/json when you need to submit image data as a base64-encoded string.

Option 1: Multipart/Form-Data (Recommended)

Headers:

Content-Type: multipart/form-data
Authorization: Bearer YOUR_LOGIN_TOKEN

Option 2: JSON with Base64

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN

Performance Tip

The Accept-Encoding: gzip header enables response compression, reducing bandwidth usage and improving performance. Most HTTP clients support gzip decompression automatically, so you can include this header to optimize your API interactions without additional handling.

Body Parameters

The image field used depends on the content type:

• multipart/form-data → use the image field (binary file)
• application/json → use the base64 field (base64-encoded string)

image file Required

Binary image file. Required when using multipart/form-data. Base64-encoded images are not accepted for multipart requests.

Requirements:

• Size: Minimum 512×512px, maximum 6000×4500px (27 megapixels)
• File size: Less than 32MB
• Formats: PNG, JPG, JPEG, BMP, WebP, HEIC/HEIF

base64 string Required

Base64-encoded image data. Required when using application/json content type.

Requirements:

• Size: Minimum 512×512px, maximum 6000×4500px (27 megapixels)
• File size: Less than 32MB (before encoding)
• Formats: PNG, JPG, JPEG, BMP, WebP, HEIC/HEIF

Example: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ..."

filename string Required

The name of the image file including its extension.

Requirements:

• Allowed file extensions: .png, .jpg, .jpeg, .bmp, .webp, .heic, .heif
• <= 255 characters

Example: "my-image.png"

model string Required

The AI detection model to use for analysis:

• AI Image 1 Ultra: "ai-image-1-ultra"

Example: "ai-image-1-ultra"

sandbox boolean default: "false"

Use sandbox mode to test your integration with the Copyleaks API without consuming any credits.

Submit images for AI detection and get returned mock results, simulating Copyleaks’ API functionality to ensure you have successfully integrated the API.

This feature is intended to be used for development purposes only.

Responses

200

200 OK

The image was successfully analyzed.

Response Schema

The response contains the following fields:

model string

The version of the AI detection model used for analysis.

result object

RLE-encoded mask data. Contains arrays of start positions and lengths for AI-detected regions.

starts array<integer>

Start positions of AI-detected segments in the flattened image array.

lengths array<integer>

Lengths of AI-detected segments corresponding to each start position.

summary object

Summary statistics of the AI detection analysis.

human float

Percentage of pixels suspected to be human-created. Range: 0.0-1.0

ai float

Percentage of pixels suspected to be AI-generated. Range: 0.0-1.0

imageInfo object

Information about the analyzed image.

shape object

Dimensions of the analyzed image.

height integer

Height of the image in pixels.

width integer

Width of the image in pixels.

metadata object

Optional metadata extracted from the image.

issuedTime string

Timestamp when the image was created (if available).

issuedBy string

The AI service or tool that created the image (if detected).

appOrDeviceUsed string

The application or device used to create the image.

contentSummary string

A summary of how the image was generated.

scannedDocument object

Metadata about the scan operation.

scanId string

The unique identifier for this scan.

actualCredits integer

The actual number of credits consumed by this scan.

expectedCredits integer

The expected number of credits for this scan.

creationTime string

ISO 8601 timestamp of when the scan was created.

Example Response

A typical response from this endpoint:

Show full example (39 lines)

{
  "model": "ai-image-1-ultra",
  "result": {
    "starts": [
      0,
      512,
      1536,
      2560
    ],
    "lengths": [
      256,
      512,
      768,
      1024
    ]
  },
  "summary": {
    "human": 0.3,
    "ai": 0.7
  },
  "imageInfo": {
    "shape": {
      "height": 1024,
      "width": 768
    },
    "metadata": {
      "issuedTime": "2025-07-23T12:44:05",
      "issuedBy": "OpenAI",
      "appOrDeviceUsed": "OpenAI-API",
      "contentSummary": "Created using generative AI"
    }
  },
  "scannedDocument": {
    "scanId": "my-scan-id-1",
    "actualCredits": 1,
    "expectedCredits": 1,
    "creationTime": "2023-01-10T10:07:58.9459512Z"
  }
}

{
  "model": "ai-image-1-ultra",
  "result": {
    "starts": [
      0,
      512,
      1536,
      2560
    ],
    "lengths": [
      256,
      512,
      768,
      1024
    ]
// ... truncated

400

400 Bad Request

Invalid request parameters, unsupported image format, or image processing issues.

401

401 Unauthorized

Authentication or authorization issues.

402

402 Payment Required - Insufficient Credits

You don't have enough credits to complete the request.

429

429 Too Many Requests

Too many requests have been sent. The request has been rejected.

500

500 Internal Server Error

The server encountered an internal error or misconfiguration.

Examples

Multipart/Form-Data Examples (Recommended)

HTTP

POST https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer YOUR_LOGIN_TOKEN

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image"; filename="test-image.png"
Content-Type: image/png

[binary image data]
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="filename"

test-image.png
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="sandbox"

true
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="model"

ai-image-1-ultra
------WebKitFormBoundary7MA4YWxkTrZu0gW--

cURL

curl --request POST \
  --url https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check \
  --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
  --form 'image=@/path/to/test-image.png' \
  --form 'filename=test-image.png' \
  --form 'sandbox=true' \
  --form 'model=ai-image-1-ultra'

JavaScript

const imageFile = document.getElementById('fileInput').files[0];
const formData = new FormData();

formData.append('image', imageFile);
formData.append('filename', imageFile.name);
formData.append('sandbox', 'true');
formData.append('model', 'ai-image-1-ultra');

const response = await fetch('https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_LOGIN_TOKEN'
  },
  body: formData
});

const result = await response.json();
console.log('AI Detection Result:', result);

Python

import requests

# Prepare the request
url = 'https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check'
headers = {
    'Authorization': 'Bearer YOUR_LOGIN_TOKEN'
}

# Prepare multipart form data
with open('test-image.png', 'rb') as image_file:
    files = {
        'image': ('test-image.png', image_file, 'image/png')
    }
    data = {
        'filename': 'test-image.png',
        'sandbox': 'true',
        'model': 'ai-image-1-ultra'
    }

    # Send the request
    response = requests.post(url, files=files, data=data, headers=headers)

result = response.json()
print(f"AI Detection Summary: {result['summary']}")

JSON Examples

HTTP

POST https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN

{
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
  "filename": "test-image.png",
  "sandbox": true,
  "model": "ai-image-1-ultra"
}

cURL

curl --request POST \
  --url https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check \
  --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
    "filename": "test-image.png",
    "sandbox": true,
    "model": "ai-image-1-ultra"
  }'

JavaScript

const imageFile = document.getElementById('fileInput').files[0];
const reader = new FileReader();

reader.onload = async function(e) {
  const base64Data = e.target.result.split(',')[1];

  const response = await fetch('https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      base64: base64Data,
      filename: imageFile.name,
      sandbox: true,
      model: 'ai-image-1-ultra'
    })
  });

  const result = await response.json();
  console.log('AI Detection Result:', result);
};

reader.readAsDataURL(imageFile);

Python

import base64
import requests

# Read and encode the image
with open('test-image.png', 'rb') as image_file:
    base64_image = base64.b64encode(image_file.read()).decode('utf-8')

# Prepare the request
url = 'https://api.copyleaks.com/v1/ai-image-detector/my-scan-123/check'
headers = {
    'Authorization': 'Bearer YOUR_LOGIN_TOKEN',
    'Content-Type': 'application/json'
}

payload = {
    'base64': base64_image,
    'filename': 'test-image.png',
    'sandbox': True,
    'model': 'ai-image-1-ultra'
}

# Send the request
response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"AI Detection Summary: {result['summary']}")