Detect Objects in an Image

Q: What happens if an object is not found?

Objects that are not found are omitted from the detectedObjects array. Look entries up by their object name rather than by position.

The Copyleaks Object Detection API locates specific objects within an image and returns a Run-Length Encoded (RLE) segmentation mask for each object it finds. The API is synchronous, so you get the results in the same API call. This guide walks you through submitting an image with a list of objects to locate using multipart/form-data, and interpreting the results.

Object detection performs segmentation only - it does not classify whether the image is AI-generated. To detect AI-generated content, see the AI Image Detection guide.

Get started

Before you begin

Before you start, ensure you have the following:

An active Copyleaks account. If you don’t have one, sign up for free.
You can find your API key on the API Dashboard.

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.

POST https://id.copyleaks.com/v3/account/login/api

Headers
Content-Type: application/json

Body
{
    "email": "[email protected]",
    "key": "00000000-0000-0000-0000-000000000000"
}

export COPYLEAKS_EMAIL="[email protected]"
export COPYLEAKS_API_KEY="your-api-key-here"

curl --request POST \
  --url https://id.copyleaks.com/v3/account/login/api \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data "{
    \"email\": \"${COPYLEAKS_EMAIL}\",
    \"key\": \"${COPYLEAKS_API_KEY}\"
  }"

from copyleaks.copyleaks import Copyleaks

EMAIL_ADDRESS = "[email protected]"
API_KEY = "your-api-key-here"

# Login to Copyleaks
auth_token = Copyleaks.login(EMAIL_ADDRESS, API_KEY)
print("Logged successfully!\nToken:", auth_token)

const { Copyleaks } = require("plagiarism-checker");

const EMAIL_ADDRESS = "[email protected]";
const API_KEY = "your-api-key-here";
const copyleaks = new Copyleaks();

// Login function
function loginToCopyleaks() {
  return copyleaks.loginAsync(EMAIL_ADDRESS, API_KEY).then(
    (loginResult) => {
      console.log("Login successful!");
      console.log("Access Token:", loginResult.access_token);
      return loginResult;
    },
    (err) => {
      console.error('Login failed:', err);
      throw err;
    }
  );
}

loginToCopyleaks();

import classes.Copyleaks;
import models.response.CopyleaksAuthToken;

String EMAIL_ADDRESS = "[email protected]";
String API_KEY = "00000000-0000-0000-0000-000000000000";

// Login to Copyleaks
try {
    CopyleaksAuthToken authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
    System.out.println("Logged in successfully!");
} catch (Exception e) {
    System.out.println("Failed to login: " + e.getMessage());
    System.exit(1);
}

Response

{
    "access_token": "<ACCESS_TOKEN>",
    ".issued": "2025-07-31T10:19:40.0690015Z",
    ".expires": "2025-08-02T10:19:40.0690016Z"
}

Save this token. It is valid for 48 hours and can be reused for subsequent API calls.

Submit for analysis

Use the Object Detection Endpoint to send an image for analysis. We suggest you provide a unique scanId for each submission.Provide the objects to locate in the objectDetection field as a JSON-encoded array of objects, for example [{"object":"face"},{"object":"hand"}].

Image Requirements

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

Object Detection Requirements

At least one entry, maximum 3 entries.
Each entry’s object value must be a non-empty string of at most 32 characters.

For testing, set sandbox=true. Sandbox mode is free and returns mock results.

curl -X POST "https://api.copyleaks.com/v1/object-detection/my-scan-123/check" \
     -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
     -F "image=@/path/to/test-image.png" \
     -F "filename=test-image.png" \
     -F "sandbox=true" \
     -F 'objectDetection=[{"object":"face"},{"object":"hand"}]'

import requests

url = 'https://api.copyleaks.com/v1/object-detection/my-scan-123/check'
headers = {'Authorization': 'Bearer YOUR_LOGIN_TOKEN'}

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',
        'objectDetection': '[{"object":"face"},{"object":"hand"}]',
    }
    response = requests.post(url, files=files, data=data, headers=headers)

result = response.json()
print(f"Detected objects: {result.get('detectedObjects')}")

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('objectDetection', JSON.stringify([{ object: 'face' }, { object: 'hand' }]));

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

const result = await response.json();
console.log('Detected objects:', result.detectedObjects);

Interpreting the response

The API response contains:

imageInfo with the image dimensions, used to decode the masks.
detectedObjects - one entry per object located in the image, each with an object name and a Run-Length Encoded (RLE) mask.
scannedImage with scan details including credits used.

Objects that were requested but not found are omitted from detectedObjects, so look entries up by object rather than by position.

Understanding the RLE Mask

Run-Length Encoding (RLE) represents each object’s region efficiently as arrays of starts positions and lengths over a flattened 1D version of the image. Decode it into a binary mask to visualize the object’s region:

Python

def decode_mask(rle_data, image_width, image_height):
    total_pixels = image_width * image_height
    mask = [0] * total_pixels
    starts = rle_data.get('starts', [])
    lengths = rle_data.get('lengths', [])
    for start, length in zip(starts, lengths):
        for j in range(length):
            position = start + j
            if position < total_pixels:
                mask[position] = 1
    return mask

# Example usage:
# result = response.json()
# width = result['imageInfo']['shape']['width']
# height = result['imageInfo']['shape']['height']
# for entry in result.get('detectedObjects', []):
#     mask = decode_mask(entry['mask'], width, height)

For a complete breakdown of all fields in the response, see the Object Detection Response documentation.

Summary

You have successfully submitted an image for object detection. You can now use the per-object masks in your application, for example to crop, blur, or highlight the detected regions.

Frequently asked questions

Is the Object Detection API synchronous?

Yes. You send the image to the check endpoint and receive the results in the same API call, with no webhook required.

How many objects can I request?

Between 1 and 3 objects per request. Each object’s name must be a non-empty string of at most 32 characters.

Does it tell me if the image is AI-generated?

No. Object detection performs segmentation only. Use the AI Image Detection API to detect AI-generated content.

What happens if an object is not found?

Objects that are not found are omitted from the detectedObjects array. Look entries up by their object name rather than by position.

Get started

Guides

Using the APIs

Concepts

Resources

Get started

Before you begin

Submit for analysis

Image Requirements

Object Detection Requirements

Interpreting the response

Understanding the RLE Mask

Summary

Frequently asked questions

Next steps

API Reference

Object Detection Response

​Get started

​Before you begin

​Login

​Submit for analysis

​Image Requirements

​Object Detection Requirements

​Interpreting the response

​Understanding the RLE Mask

​Summary

​Frequently asked questions

​Next steps

API Reference

Object Detection Response

Get started

Before you begin

Login

Submit for analysis

Image Requirements

Object Detection Requirements

Interpreting the response

Understanding the RLE Mask

Summary

Frequently asked questions

Next steps