Detect Objects - Detect Objects

Service:

Azure AI Services

API Version:

3.2

Performs object detection on the specified image. Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.

POST {Endpoint}/vision/v3.2/detect

With optional parameters:

POST {Endpoint}/vision/v3.2/detect?model-version={model-version}

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoints.
model-version	query		string pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$	Optional parameter to specify the version of the AI model. Accepted values are: "latest", "2021-04-01", "2021-05-01". Defaults to "latest".

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string

Request Body

Name	Required	Type	Description
url	True	string	Publicly reachable URL of an image.

Responses

Name	Type	Description
200 OK	DetectResult	The response include the detected objects in JSON format.
Other Status Codes	ComputerVisionErrorResponse	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Successful DetectObjects request

Sample request

HTTP

POST https://westus.api.cognitive.microsoft.com/vision/v3.2/detect


{
  "url": "{url}"
}

Sample response

Status code:

200

{
  "objects": [
    {
      "rectangle": {
        "x": 0,
        "y": 0,
        "w": 50,
        "h": 50
      },
      "object": "tree",
      "confidence": 0.9,
      "parent": {
        "object": "plant",
        "confidence": 0.95
      }
    }
  ],
  "requestId": "1ad0e45e-b7b4-4be3-8042-53be96103337",
  "metadata": {
    "width": 100,
    "height": 100,
    "format": "Jpeg"
  },
  "modelVersion": "2021-04-01"
}

Definitions

Name	Description
BoundingRect	A bounding box for an area inside an image.
ComputerVisionError	The API request error.
ComputerVisionErrorCodes	The error code.
ComputerVisionErrorResponse	The API error response.
ComputerVisionInnerError	Details about the API request error.
ComputerVisionInnerErrorCodeValue	The error code.
DetectedObject	An object detected in an image.
DetectResult	Result of a DetectImage call.
ImageMetadata	Image metadata.
ImageUrl
ObjectHierarchy	An object detected inside an image.

BoundingRect

Object

A bounding box for an area inside an image.

Name	Type	Description
h	integer (int32)	Height measured from the top-left point of the area, in pixels.
w	integer (int32)	Width measured from the top-left point of the area, in pixels.
x	integer (int32)	X-coordinate of the top left point of the area, in pixels.
y	integer (int32)	Y-coordinate of the top left point of the area, in pixels.

ComputerVisionError

Object

The API request error.

Name	Type	Description
code	ComputerVisionErrorCodes	The error code.
innererror	ComputerVisionInnerError	Inner error contains more specific information.
message	string	A message explaining the error reported by the service.

ComputerVisionErrorCodes

Enumeration

The error code.

Value	Description
InvalidRequest
InvalidArgument
InternalServerError
ServiceUnavailable

ComputerVisionErrorResponse

Object

The API error response.

Name	Type	Description
error	ComputerVisionError	Error contents.

ComputerVisionInnerError

Object

Details about the API request error.

Name	Type	Description
code	ComputerVisionInnerErrorCodeValue	The error code.
message	string	Error message.

ComputerVisionInnerErrorCodeValue

Enumeration

The error code.

Value	Description
InvalidImageFormat
UnsupportedMediaType
InvalidImageUrl
NotSupportedFeature
NotSupportedImage
Timeout
InternalServerError
InvalidImageSize
BadArgument
DetectFaceError
NotSupportedLanguage
InvalidThumbnailSize
InvalidDetails
InvalidModel
CancelledRequest
NotSupportedVisualFeature
FailedToProcess
Unspecified
StorageException

DetectedObject

Object

An object detected in an image.

Name	Type	Description
confidence	number (double)	Confidence score of having observed the object in the image, as a value ranging from 0 to 1.
object	string	Label for the object.
parent	ObjectHierarchy	The parent object, from a taxonomy perspective. The parent object is a more generic form of this object. For example, a 'bulldog' would have a parent of 'dog'.
rectangle	BoundingRect	Approximate location of the detected object.

DetectResult

Object

Result of a DetectImage call.

Name	Type	Description
metadata	ImageMetadata	Image metadata.
modelVersion	string pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$	Version of the AI model.
objects	DetectedObject[]	An array of detected objects.
requestId	string	Id of the REST API request.

ImageMetadata

Object

Image metadata.

Name	Type	Description
format	string	Image format.
height	integer (int32)	Image height, in pixels.
width	integer (int32)	Image width, in pixels.

ImageUrl

Object

Name	Type	Description
url	string	Publicly reachable URL of an image.

ObjectHierarchy

Object

An object detected inside an image.

Name	Type	Description
confidence	number (double)	Confidence score of having observed the object in the image, as a value ranging from 0 to 1.
object	string	Label for the object.
parent	ObjectHierarchy	The parent object, from a taxonomy perspective. The parent object is a more generic form of this object. For example, a 'bulldog' would have a parent of 'dog'.