# Object Counter: Detect & Count Objects in Any Image (`nookforgestudio/object-counter`) Actor

Detect and count people, vehicles, boats, animals and 80 everyday objects in photos, drone shots and large images. Returns counts, bounding boxes and annotated previews, with tiled inference for small objects. Pay per image.

- **URL**: https://apify.com/nookforgestudio/object-counter.md
- **Developed by:** [Nookforgestudio](https://apify.com/nookforgestudio) (community)
- **Categories:** AI, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 image analyzeds

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 Counter: Detect & Count Objects in Any Image

Count **people, cars, trucks, boats, bikes, animals and 80 everyday objects** in photos, drone shots and high-resolution images. Normal detectors shrink a big image to about 640 px before looking at it, so anything small, like cars in a parking lot or people in a crowd, simply disappears. This Actor uses **sliced inference**: it scans the image in overlapping tiles at full resolution, then merges the results so each object is counted once.

Same public photos, same model, single pass vs. tiled:

| Photo | Single pass | **Tiled (this Actor)** |
|---|---|---|
| Aerial marina, 3613×2400 | 5 boats | **91 boats** |
| Festival crowd, 3586×2981 | 18 people | **105 people** |
| Parking lot, 2304×2304 | 18 cars | **31 cars** |

Try them in the examples below.

- 🔎 **Small-object mode**: overlapping tiles plus a full-image pass, with partial boxes at tile edges merged into whole objects
- 🧮 **Counts per class** plus a grand total for the run
- 📦 **Every box**: label, confidence and `[x0, y0, x1, y1]` in original image pixels
- 🖼️ **Annotated preview** JPEG per image, with a public link
- 🎯 **Count only what you need**: `["car", "truck"]`, `["people"]`, `["boat"]`
- 🔒 **Runs inside the Actor**: images are not sent to any third-party AI API
- 💸 **Pay per image (plus per tile in small-object mode); failed images are free**

#### Use cases

- **Parking and traffic**: count cars, trucks and buses in lot or street photos
- **Events and venues**: estimate people in crowd photos
- **Marinas and waterfronts**: count boats
- **Real estate and retail**: count chairs, tables, bottles or other items in photos
- **Data pipelines and AI agents**: add "how many X are in this image?" to any workflow through the API or MCP

#### Ready-made examples

- [Count cars in parking lot photos](https://apify.com/nookforgestudio/object-counter/examples/count-cars-in-parking-lot-photos)
- [Count people in crowd and event photos](https://apify.com/nookforgestudio/object-counter/examples/count-people-in-crowd-photos)
- [Count boats in marina and aerial photos](https://apify.com/nookforgestudio/object-counter/examples/count-boats-in-marina-aerial-photos)

#### How it compares

| | Typical single-pass detector | Vision LLM API | **Object Counter** |
|---|---|---|---|
| Small objects in large images | Missed after downscaling to ~640 px | Approximate | **Found with overlapping full-resolution tiles** |
| Exact per-class counts and boxes | Yes | Rarely consistent | **Yes, plus annotated preview** |
| Images sent to a third party | Depends | Yes | **No, runs inside the Actor** |
| Pricing | Per image | Per token | **Per image, plus per tile only for large images** |

#### How to use

1. Paste image links into **Image URLs** (or read them from a scraper's dataset).
2. Optionally list the **Objects to count**. Leave empty for all 80 classes.
3. Keep **Small-object mode** on `auto` and click **Start**.

#### Input example

```json
{
  "urls": ["https://ultralytics.com/images/bus.jpg"],
  "classes": ["person", "bus"],
  "tiling": "auto",
  "minScore": "0.35",
  "saveAnnotatedImages": true
}
```

#### Output example

Real output for the image above:

```json
{
  "source": "https://ultralytics.com/images/bus.jpg",
  "width": 810,
  "height": 1080,
  "total": 5,
  "counts": {"person": 4, "bus": 1},
  "tilesUsed": 4,
  "annotatedImageUrl": "https://api.apify.com/v2/key-value-stores/.../records/annotated-00001.jpg",
  "detections": [
    {"label": "bus", "score": 0.9421, "box": [16, 232, 791, 719]},
    {"label": "person", "score": 0.9094, "box": [668, 458, 810, 883]}
  ]
}
```

A `SUMMARY` record in the run's key-value store holds the totals across all images.

#### Pricing

| Event | Price | When |
|---|---|---|
| Image analyzed | **$0.002** | Each image successfully processed |
| Tile analyzed | **$0.0003** | Each extra tile, only for images over ~960 px with tiling on |
| Actor start | $0.00005 per GB | Once per run |

| Example | Cost |
|---|---|
| 1,000 phone-size photos (no tiling) | $2.00 |
| One 2304×2304 photo (25 tiles) | $0.0095 |
| One 12 MP photo (48 tiles) | $0.0164 |

Platform usage is included. Images that fail to download or decode are free. Set tiling to `never` for the cheapest single pass, cap **Max tiles per image**, or set the run's **maximum cost**; the Actor stops cleanly at the limit.

#### FAQ

**Can it count objects that aren't in the list?** Not out of the box. The model knows the 80 classes above. For custom objects (products, defects, equipment), see custom work below.

**Do I pay for images that fail?** No. Download or decode failures return an error row and are not charged.

**Why are there extra classes in my counts?** Leave **Objects to count** empty to count everything, or list only the classes you want.

#### Custom work

Need a custom-trained detector, video or a full vision pipeline? Contact [Nookforge Studio](https://apify.com/nookforgestudio).

#### Supported objects

person, bicycle, car, motorcycle, airplane, bus, train, truck, boat, traffic light, fire hydrant, stop sign, parking meter, bench, bird, cat, dog, horse, sheep, cow, elephant, bear, zebra, giraffe, backpack, umbrella, handbag, tie, suitcase, frisbee, skis, snowboard, sports ball, kite, baseball bat, baseball glove, skateboard, surfboard, tennis racket, bottle, wine glass, cup, fork, knife, spoon, bowl, banana, apple, sandwich, orange, broccoli, carrot, hot dog, pizza, donut, cake, chair, couch, potted plant, bed, dining table, toilet, tv, laptop, mouse, remote, keyboard, cell phone, microwave, oven, toaster, sink, refrigerator, book, clock, vase, scissors, teddy bear, hair drier, toothbrush

#### Use with AI agents (MCP)

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=nookforgestudio/object-counter"
```

Then ask: *"How many cars are in this photo? https://..."*

#### Use via API

```bash
curl -X POST "https://api.apify.com/v2/acts/nookforgestudio~object-counter/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://ultralytics.com/images/bus.jpg"], "classes": ["person"]}'
```

Also works from Make, n8n and Zapier through Apify's integrations.

#### Accuracy notes

- Detection is probabilistic. Counts are estimates; very dense crowds, heavy occlusion and straight-down (nadir) aerial views of tiny objects reduce accuracy.
- Lower **Minimum confidence** to find more objects (and more false positives); raise it for precision.
- The model recognizes the 80 classes above only.

#### Model and license

Detection uses YOLOX-S (Apache-2.0) by Megvii, run with ONNX Runtime.

#### Support

Open an issue in the **Issues** tab with an image link and what you expected.

# Actor input Schema

## `urls` (type: `array`):

Direct links to images (JPG, PNG, WebP, TIFF, BMP).

## `classes` (type: `array`):

Leave empty to count everything. Examples: person, car, truck, bus, boat, bicycle, motorcycle, dog, bird, cow, sheep, chair, bottle. Plurals like 'cars' work.

## `datasetId` (type: `string`):

Optional. ID of an Apify dataset (e.g. scraper output) that contains image URLs.

## `urlField` (type: `string`):

Dot path to the field with image URL(s), e.g. 'imageUrl' or 'images'. Arrays are expanded.

## `tiling` (type: `string`):

'auto' slices images larger than about 1000 px into overlapping tiles so small objects are found. 'always' forces it, 'never' runs one pass only (cheapest).

## `minScore` (type: `string`):

Detections below this confidence (0 to 1) are ignored. Lower finds more objects and more false positives.

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

Store a JPEG with boxes drawn and return its URL.

## `includeDetections` (type: `boolean`):

Return each detection with label, confidence and \[x0, y0, x1, y1] in original image pixels.

## `tileSize` (type: `integer`):

Tile edge in image pixels. Smaller tiles find smaller objects but cost more tiles.

## `tileOverlap` (type: `string`):

Fraction of overlap between tiles (0 to 0.5).

## `maxTilesPerImage` (type: `integer`):

Caps cost per image. If an image needs more tiles, tiles are enlarged to fit.

## `maxImageSide` (type: `integer`):

Larger images are downscaled to this long-side length first.

## `maxFiles` (type: `integer`):

Safety cap on images per run.

## Actor input object example

```json
{
  "urls": [
    "https://raw.githubusercontent.com/Megvii-BaseDetection/YOLOX/main/assets/dog.jpg"
  ],
  "urlField": "url",
  "tiling": "auto",
  "minScore": "0.35",
  "saveAnnotatedImages": true,
  "includeDetections": true,
  "tileSize": 640,
  "tileOverlap": "0.2",
  "maxTilesPerImage": 64,
  "maxImageSide": 8000,
  "maxFiles": 1000
}
```

# Actor output Schema

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

One row per image with total, per-class counts, tiles used and a preview link.

## `summary` (type: `string`):

Total objects and per-class counts across all images in the run.

## `previews` (type: `string`):

JPEG previews with bounding boxes drawn.

# 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 = {
    "urls": [
        "https://raw.githubusercontent.com/Megvii-BaseDetection/YOLOX/main/assets/dog.jpg"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nookforgestudio/object-counter").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 = { "urls": ["https://raw.githubusercontent.com/Megvii-BaseDetection/YOLOX/main/assets/dog.jpg"] }

# Run the Actor and wait for it to finish
run = client.actor("nookforgestudio/object-counter").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 '{
  "urls": [
    "https://raw.githubusercontent.com/Megvii-BaseDetection/YOLOX/main/assets/dog.jpg"
  ]
}' |
apify call nookforgestudio/object-counter --silent --output-dataset

```

## MCP server setup

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

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/xMJOBFo0WpYZkOZJI/builds/CR4bYnueRMaNa0GG7/openapi.json