Skip to main content
POST
/
v1
/
detect
cURL
curl --request POST \
  --url https://api.perceptron.inc/v1/detect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "media": {
    "image_url": "<string>",
    "type": "image"
  },
  "categories": [
    "<string>"
  ],
  "config": {
    "enable_thinking": false
  },
  "exemplars": [
    {
      "annotations": [
        {
          "mention": "<string>",
          "index": 123,
          "label": "<string>",
          "point": {
            "x": 123,
            "y": 123
          },
          "point_box": {
            "bottom_right": {
              "x": 123,
              "y": 123
            },
            "top_left": {
              "x": 123,
              "y": 123
            }
          },
          "timestamp": 123
        }
      ],
      "media": {
        "image_url": "<string>",
        "type": "image"
      }
    }
  ],
  "negative_exemplars": [
    {
      "media": {
        "image_url": "<string>",
        "type": "image"
      }
    }
  ]
}
'
{
  "detections": [
    {
      "mention": "<string>",
      "point": {
        "x": 123,
        "y": 123
      },
      "point_box": {
        "bottom_right": {
          "x": 123,
          "y": 123
        },
        "top_left": {
          "x": 123,
          "y": 123
        }
      }
    }
  ]
}

​
Overview

The Detect API returns grounded object detections for a single image. Use it when you want a direct detection workflow without building a chat-completions prompt. Requests can include text categories, annotated positive exemplars, both together, or no targets for exhaustive object detection. You can also include negative_exemplars, but only alongside at least one category or positive exemplar. Coordinates for exemplar annotations and returned detections are image pixels. /v1/detect supports image inputs only and returns detections plus a finish_reason. The response does not include confidence scores. For request shapes, worked examples, supported permutations, and limits, see the Detect capability guide.

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your Perceptron API key

Body

application/json
​
media
object
required
​
categories
string[] | null

Category names to detect. Entries must be non-empty and must not contain commas.

​
config
object
​
exemplars
object[] | null
​
negative_exemplars
object[] | null

Response

Detection completed successfully.

​
detections
object[]
required
​
finish_reason
enum<string>
required
Available options:
complete,
max_tokens