Share via

Faces - Detect

Service:
Azure AI Services
API Version:
2025-05-01-preview

Detect faces in an image.

POST {endpoint}/contentunderstanding/faces:detect?api-version=2025-05-01-preview

URI Parameters

Name In Required Type Description
endpoint
 path True

string (uri)

Content Understanding service endpoint.
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Header

Name Required Type Description
x-ms-client-request-id

string (uuid)

An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Name Type Description
data

string (byte)

Base64-encoded image data. Only one of url or data should be specified.
maxDetectedFaces

integer (int32)

Maximum number of faces to return (up to 100).
url

string

Image URL. Only one of url or data should be specified.

Responses

Name Type Description
200 OK

DetectFacesResult

The request has succeeded.
Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/token

Scopes

Name Description
https://cognitiveservices.azure.com/.default

Examples

Detect Faces in an Image

Sample request

POST {endpoint}/contentunderstanding/faces:detect?api-version=2025-05-01-preview

{
  "url": "https://mystorageaccount.blob.core.windows.net/images/container/file.jpg",
  "maxDetectedFaces": 50
}

Sample response

Status code:
200 
{
  "detectedFaces": [
    {
      "boundingBox": {
        "left": 33,
        "top": 73,
        "width": 262,
        "height": 324
      }
    },
    {
      "boundingBox": {
        "left": 87,
        "top": 96,
        "width": 235,
        "height": 345
      }
    }
  ]
}

Definitions

Name Description
Azure.Core.Foundations.Error

The error object.
Azure.Core.Foundations.ErrorResponse

A response containing error details.
Azure.Core.Foundations.InnerError

An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
BoundingBox

Bounding box in an image.
DetectedBoundingBox

Detected bounding box of an object.
DetectFacesParameters

Detect faces parameters.
DetectFacesResult

Detect faces response.

Azure.Core.Foundations.Error

Object

The error object.

Name Type Description
code

string

One of a server-defined set of error codes.
details

Azure.Core.Foundations.Error[]

An array of details about specific errors that led to this reported error.
innererror

Azure.Core.Foundations.InnerError

An object containing more specific information than the current object about the error.
message

string

A human-readable representation of the error.
target

string

The target of the error.

Azure.Core.Foundations.ErrorResponse

Object

A response containing error details.

Name Type Description
error

Azure.Core.Foundations.Error

The error object.

Azure.Core.Foundations.InnerError

Object

An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.

Name Type Description
code

string

One of a server-defined set of error codes.
innererror

Azure.Core.Foundations.InnerError

Inner error.

BoundingBox

Object

Bounding box in an image.

Name Type Description
height

integer (int32)

Height of the bounding box.
left

integer (int32)

Left coordinate of the bounding box.
top

integer (int32)

Top coordinate of the bounding box.
width

integer (int32)

Width of the bounding box.

DetectedBoundingBox

Object

Detected bounding box of an object.

Name Type Description
boundingBox

BoundingBox

Bounding box of the detected face.

DetectFacesParameters

Object

Detect faces parameters.

Name Type Default value Description
data

string (byte)

Base64-encoded image data. Only one of url or data should be specified.
maxDetectedFaces

integer (int32)

100

Maximum number of faces to return (up to 100).
url

string

Image URL. Only one of url or data should be specified.

DetectFacesResult

Object

Detect faces response.

Name Type Description
detectedFaces

DetectedBoundingBox[]

List of detected faces.