Object Detector

Overview

Detection uses DETR (DEtection TRansformer) with a ResNet-50 backbone, trained by Meta AI on COCO 2017 and released under Apache 2.0, run as an 8-bit quantized ONNX model on APIVerve's servers. The image is decoded, turned upright from its EXIF orientation and, if larger, scaled so its longer side is at most 1,333 pixels, which is the most the model reads. DETR predicts 100 candidate objects per image directly, with no anchor boxes or non-maximum suppression; candidates below `minConfidence` are dropped and the rest are mapped back to the original image size.

`confidence` is the model's class probability, 0 to 1, rounded to 4 places. `box` is in pixels of the upright image: `x` and `y` are the top-left corner, measured from the top-left of the image. `normalizedBox` divides those by `imageWidth` and `imageHeight`. Objects are sorted by confidence, and `counts` tallies the returned objects by label, after the `labels` filter.

`labels` accepts the 80 COCO class names (`traffic light`, `cell phone`, `dining table` and so on), case-insensitive, with underscores or hyphens for spaces, simple plurals and common synonyms (sofa, television, phone, bike, motorbike, fridge). An unknown label returns 400 naming it. URLs are downloaded by APIVerve from public hosts only, with a 10 MB limit; the image service never fetches caller URLs itself.

Live Test Object Detector API →

Endpoint

One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.

1
2
3
4
5
6
7

curl -X POST https://api.apiverve.com/v1/objectdetector \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "image": "http://images.cocodataset.org/val2017/000000039769.jpg",
  "minConfidence": 0.5
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const res = await fetch('https://api.apiverve.com/v1/objectdetector', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "image": "http://images.cocodataset.org/val2017/000000039769.jpg",
  "minConfidence": 0.5
}),
});

if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const { data } = await res.json();
console.log(data);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import requests

res = requests.post(
    "https://api.apiverve.com/v1/objectdetector",
    headers={"x-api-key": "your_api_key_here"},
    json={
    "image": "http://images.cocodataset.org/val2017/000000039769.jpg",
    "minConfidence": 0.5
},
    timeout=15,
)
res.raise_for_status()

print(res.json()["data"])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "image": "http://images.cocodataset.org/val2017/000000039769.jpg",
  "minConfidence": 0.5
}`)
	req, _ := http.NewRequest("POST", "https://api.apiverve.com/v1/objectdetector", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "your_api_key_here")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.

Authentication

Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.

Parameters

Sent as JSON in the request body. Premium parameters are accepted on every plan but only take effect on plans that include them.

Response

Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

{
  "status": "ok",
  "error": null,
  "data": {
    "imageWidth": 640,
    "imageHeight": 480,
    "objectCount": 5,
    "counts": {
      "cat": 2,
      "remote": 2,
      "couch": 1
    },
    "objects": [
      {
        "label": "cat",
        "confidence": 0.999,
        "box": {
          "x": 4,
          "y": 51,
          "width": 320,
          "height": 417
        },
        "normalizedBox": {
          "x": 0.0063,
          "y": 0.1062,
          "width": 0.5,
          "height": 0.8688
        }
      },
      {
        "label": "cat",
        "confidence": 0.9987,
        "box": {
          "x": 331,
          "y": 20,
          "width": 309,
          "height": 350
        },
        "normalizedBox": {
          "x": 0.5172,
          "y": 0.0417,
          "width": 0.4828,
          "height": 0.7292
        }
      },
      {
        "label": "remote",
        "confidence": 0.9984,
        "box": {
          "x": 329,
          "y": 67,
          "width": 42,
          "height": 128
        },
        "normalizedBox": {
          "x": 0.5141,
          "y": 0.1396,
          "width": 0.0656,
          "height": 0.2667
        }
      },
      {
        "label": "remote",
        "confidence": 0.9975,
        "box": {
          "x": 29,
          "y": 68,
          "width": 160,
          "height": 50
        },
        "normalizedBox": {
          "x": 0.0453,
          "y": 0.1417,
          "width": 0.25,
          "height": 0.1042
        }
      },
      {
        "label": "couch",
        "confidence": 0.9961,
        "box": {
          "x": 0,
          "y": 0,
          "width": 636,
          "height": 472
        },
        "normalizedBox": {
          "x": 0,
          "y": 0,
          "width": 0.9938,
          "height": 0.9833
        }
      }
    ],
    "minConfidence": 0.5,
    "labels": null
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.

Object Labels

The 80 COCO object classes the labels parameter accepts

Use cases

Counting and Occupancy

Count people, cars or bicycles in camera snapshots to measure footfall, parking use or traffic.

Image Tagging

Tag uploaded photos with the objects they contain so they can be searched and filtered in a media library.

Content Checks

Confirm that listing photos actually show the item for sale, such as a car, bicycle or couch, before they are published.

Smart Cropping

Crop images around the main subject using its bounding box instead of the centre of the frame.

Other ways to use Object Detector

Set up Object Detector on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.

Related

More in Images: