# Object Detection and Image Tagging in bulk (DETR) (`examsens.ai/object-detection`) Actor

Finds the objects in every image URL you list with DETR ResNet-50, running inside the actor with no outside API: label, confidence score and bounding box for each object, a count per label and tags for each image, plus optional annotated images.

- **URL**: https://apify.com/examsens.ai/object-detection.md
- **Developed by:** [Ed Rayyis](https://apify.com/examsens.ai) (community)
- **Categories:** AI, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.50 / 1,000 image processeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Object Detection and Image Tagging in bulk (DETR)

List image URLs and get back the objects in each picture: what each one is, how confident the model is, and where it sits as a bounding box. Each image also gets a count per label and a short list of tags.

Detection runs inside the actor with DETR ResNet-50, so no image is sent to an outside API and there's no key to supply. The model was trained on the COCO 2017 object detection dataset and is released under the Apache 2.0 license \[1]. Its model card reports an average precision (AP) of 42.0 on COCO 2017 validation \[1].

### What you get for each image

- `objects`: one entry per detection with `label`, `score` from 0 to 1, `box` in pixels (`xmin`, `ymin`, `xmax`, `ymax`) and `boxNormalized` as fractions of the width and height
- `objectCount`, `labelCounts` such as `{"person": 4, "sports ball": 1}`, and `labels`, the unique labels with the most frequent first
- `width`, `height` and `inputFormat` of the image as read, after it's turned upright from its EXIF orientation
- `processingSeconds` for the detection itself
- `annotatedImageUrl` when you turn on annotated images: a JPEG copy with the boxes and labels drawn on it, stored in the run's key value store

Labels come from the COCO label list the model ships with: person, bicycle, car, motorcycle, airplane, bus, train, truck, boat, traffic light, fire hydrant, street sign, stop sign, parking meter, bench, bird, cat, dog, horse, sheep, cow, elephant, bear, zebra, giraffe, hat, backpack, umbrella, shoe, eye glasses, handbag, tie, suitcase, frisbee, skis, snowboard, sports ball, kite, baseball bat, baseball glove, skateboard, surfboard, tennis racket, bottle, plate, wine glass, cup, fork, knife, spoon, bowl, banana, apple, sandwich, orange, broccoli, carrot, hot dog, pizza, donut, cake, chair, couch, potted plant, bed, mirror, dining table, window, desk, toilet, door, tv, laptop, mouse, remote, keyboard, cell phone, microwave, oven, toaster, sink, refrigerator, blender, book, clock, vase, scissors, teddy bear, hair drier and toothbrush. The model names only objects on that list.

### Input

- Image URLs (required). Direct links to JPEG, PNG, WebP, GIF, BMP, TIFF and other formats Pillow reads. For an animated image, the first frame is analyzed. Transparent areas are filled with white.
- Minimum confidence, 0.9 by default. Try 0.5 to 0.7 when small or partly hidden objects matter, and expect more wrong labels at the lower end.
- Only these labels, for example `person` or `car`. Leave it empty to get every label.
- Maximum objects per image, keeping the highest scores (0 means no limit).
- Save annotated images, off by default.
- Maximum file size, 25 MB by default.

### Output

The dataset has one row per image. A link that fails to download, answers with an error status, or isn't an image gets one row with `ok` false and the reason in `error`, and the run moves on to the next image. An `OUTPUT` record in the key value store gives images processed, images failed and whether the run stopped at your spending limit.

### Speed and memory

The default run memory is 2,048 MB. On Apify at that setting, the 640 by 480 sample photo took 1.35 seconds to analyze and the run peaked at 566 MB of memory. Bigger photos cost little extra time, because every image is resized to 800 pixels on its short side (1,333 at most on the long side) before detection: on one CPU thread, a 12 megapixel photo took 2.1 seconds against 1.6 for the 640 by 480 one. Apify gives a run one full CPU core for every 4,096 MB of memory and a share of a core below that \[2], so a run with more memory gets through images faster.

### Pricing

Pay per event: one event per image processed. Images that fail aren't charged. When the run reaches the maximum charge you set, it stops before the next image, and every result row in the dataset is a paid one.

### Support

Questions and problems: the Issues tab on this page. Replies are written by an AI assistant on behalf of the developer and reviewed by the developer.

### References

\[1] Hugging Face, facebook/detr-resnet-50 model card, sections "Training data" and "Evaluation results", and the license tag. https://huggingface.co/facebook/detr-resnet-50
\[2] Apify documentation, Usage and resources, section "CPU". https://docs.apify.com/platform/actors/running/usage-and-resources

# Actor input Schema

## `imageUrls` (type: `array`):

Direct links to image files (JPEG, PNG, WebP, GIF, BMP, TIFF and other formats Pillow reads).

## `scoreThreshold` (type: `number`):

Objects scored below this are left out. Lower it to catch more objects, with more false detections.

## `onlyLabels` (type: `array`):

Return only objects with these COCO class names, for example person, car, dog, bottle. Leave empty for every class.

## `maxObjects` (type: `integer`):

Keep only the highest scoring objects. 0 means no limit.

## `saveAnnotatedImages` (type: `boolean`):

Draw the boxes and labels on a copy of each image, store it as a JPEG in the key value store and link it in the result.

## `maxFileSizeMb` (type: `integer`):

Skip source files larger than this, with an error item.

## Actor input object example

```json
{
  "imageUrls": [
    {
      "url": "http://images.cocodataset.org/val2017/000000039769.jpg"
    }
  ],
  "scoreThreshold": 0.9,
  "maxObjects": 0,
  "saveAnnotatedImages": false,
  "maxFileSizeMb": 25
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "imageUrls": [
        {
            "url": "http://images.cocodataset.org/val2017/000000039769.jpg"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("examsens.ai/object-detection").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "imageUrls": [{ "url": "http://images.cocodataset.org/val2017/000000039769.jpg" }] }

# Run the Actor and wait for it to finish
run = client.actor("examsens.ai/object-detection").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "imageUrls": [
    {
      "url": "http://images.cocodataset.org/val2017/000000039769.jpg"
    }
  ]
}' |
apify call examsens.ai/object-detection --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,examsens.ai/object-detection"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/K9z5VhygvaPOge7NI/builds/AbA6aLO9wnXcI1qoa/openapi.json