swagger: '2.0'
info:
version: 1.0-preview
title: Microsoft Azure Face Client
description: An API for face detection, verification, and identification.
securityDefinitions:
apim_key:
type: apiKey
name: Ocp-Apim-Subscription-Key
in: header
security:
- apim_key: []
x-ms-parameterized-host:
hostTemplate: '{Endpoint}/face/v1.0-preview'
useSchemePrefix: false
parameters:
- $ref: '#/parameters/Endpoint'
paths:
/findsimilars:
post:
description: >-
Given query face's faceId, to search the similar-looking faces from a
faceId array, a face list or a large face list. faceId array contains
the faces created by [Face - Detect With
Url](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl) or
[Face - Detect With
Stream](https://docs.microsoft.com/rest/api/faceapi/face/detectwithstream),
which will expire at the time specified by faceIdTimeToLive after
creation. A "faceListId" is created by [FaceList -
Create](https://docs.microsoft.com/rest/api/faceapi/facelist/create)
containing persistedFaceIds that will not expire. And a
"largeFaceListId" is created by [LargeFaceList -
Create](https://docs.microsoft.com/rest/api/faceapi/largefacelist/create)
containing persistedFaceIds that will also not expire. Depending on the
input the returned similar faces list contains faceIds or
persistedFaceIds ranked by similarity.<br>Find similar has two working
modes, "matchPerson" and "matchFace". "matchPerson" is the default mode
that it tries to find faces of the same person as possible by using
internal same-person thresholds. It is useful to find a known person's
other photos. Note that an empty list will be returned if no faces pass
the internal thresholds. "matchFace" mode ignores same-person thresholds
and returns ranked similar faces anyway, even the similarity is low. It
can be used in the cases like searching celebrity-looking faces.<br>The
'recognitionModel' associated with the query face's faceId should be the
same as the 'recognitionModel' used by the target faceId array, face
list or large face list.<br>
operationId: microsoftAzureFaceFindsimilar
parameters:
- name: body
in: body
description: Request body for Find Similar.
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/FindSimilarRequest'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: >-
A successful call returns an array of the most similar faces
represented in faceId if the input parameter is faceIds or
persistedFaceId if the input parameter is faceListId.
schema:
$ref: '#/definitions/SimilarFaces'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Find similar results example:
$ref: ./examples/FindSimilar.json
summary: Microsoft Azure Post Findsimilars
tags:
- Findsimilars
/group:
post:
description: >-
Divide candidate faces into groups based on face similarity.<br>* The
output is one or more disjointed face groups and a messyGroup. A face
group contains faces that have similar looking, often of the same
person. Face groups are ranked by group size, i.e. number of faces.
Notice that faces belonging to a same person might be split into several
groups in the result.<br>* MessyGroup is a special face group containing
faces that cannot find any similar counterpart face from original faces.
The messyGroup will not appear in the result if all faces found their
counterparts.<br>* Group API needs at least 2 candidate faces and 1000
at most. We suggest to try [Face -
Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface)
when you only have 2 candidate faces.<br>* The 'recognitionModel'
associated with the query faces' faceIds should be the same.<br>
operationId: microsoftAzureFaceGroup
parameters:
- name: body
description: Request body for grouping.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/GroupRequest'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: >-
A successful call returns one or more groups of similar faces (rank
by group size) and a messyGroup.
schema:
$ref: '#/definitions/GroupResult'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Group example:
$ref: ./examples/Group.json
summary: Microsoft Azure Post Group
tags:
- Group
/identify:
post:
description: >-
1-to-many identification to find the closest matches of the specific
query person face from a person group, large person group, person
directory dynamic person group or person directory personIds array.<br>
For each face in the faceIds array, Face Identify will compute
similarities between the query face and all the faces in the person
group (given by personGroupId) or large person group (given by
largePersonGroupId), and return candidate person(s) for that face ranked
by similarity confidence. The person group/large person group should be
trained to make it ready for identification. See more in [PersonGroup -
Train](https://docs.microsoft.com/rest/api/faceapi/persongroup/train)
and [LargePersonGroup -
Train](https://docs.microsoft.com/rest/api/faceapi/largepersongroup/train).<br><br>
<br>Remarks:<br>* The algorithm allows more than one face to be
identified independently at the same request, but no more than 10
faces.<br>* Each person in the person group/large person group could
have more than one face, but no more than 248 faces.<br>* Higher face
image quality means better identification precision. Please consider
high-quality faces: frontal, clear, and face size is 200x200 pixels (100
pixels between eyes) or bigger.<br>* Number of candidates returned is
restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no
person is identified, the returned candidates will be an empty
array.<br>* Try [Face - Find
Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar)
when you need to find similar faces from a face list/large face list
instead of a person group/large person group.<br>* The
'recognitionModel' associated with the query faces' faceIds should be
the same as the 'recognitionModel' used by the target person group or
large person group.<br>
operationId: microsoftAzureFaceIdentify
parameters:
- name: body
description: Request body for identify operation.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/IdentifyRequest'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: >-
A successful call returns the identified candidate person(s) for
each query face.
schema:
$ref: '#/definitions/IdentifyResults'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Identify example:
$ref: ./examples/Identify.json
summary: Microsoft Azure Post Identify
tags:
- Identify
/verify:
post:
description: >-
Verify whether two faces belong to a same person or whether one face
belongs to a person.<br><br>Remarks:<br>* Higher face image quality
means better identification precision. Please consider high-quality
faces: frontal, clear, and face size is 200x200 pixels (100 pixels
between eyes) or bigger.<br>* For the scenarios that are sensitive to
accuracy please make your own judgment.<br>* The 'recognitionModel'
associated with the query faces' faceIds should be the same as the
'recognitionModel' used by the target face, person group or large person
group.<br>
operationId: microsoftAzureFaceVerifyfacetoface
parameters:
- name: body
description: Request body for face to face verification.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/VerifyFaceToFaceRequest'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful call returns the verification result.
schema:
$ref: '#/definitions/VerifyResult'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Verify faces example:
$ref: ./examples/VerifyFaceToFace.json
summary: Microsoft Azure Post Verify
tags:
- Verify
/persongroups/{personGroupId}/persons:
post:
description: Create a new person in a specified person group.
operationId: microsoftAzurePersongrouppersonCreate
parameters:
- $ref: '#/parameters/personGroupId'
- name: body
description: Request body for creating new person.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/NameAndUserDataContract'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful call returns a new personId created.
schema:
$ref: '#/definitions/Person'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Create new person for person group example:
$ref: ./examples/CreateNewPersonGroupPerson.json
summary: Microsoft Azure Post Persongroups Persongroupid Persons
tags:
- Persongroups
get:
description: >-
List all persons in a person group, and retrieve person information
(including personId, name, userData and persistedFaceIds of registered
faces of the person).
operationId: microsoftAzurePersongrouppersonList
parameters:
- $ref: '#/parameters/personGroupId'
- name: start
description: Starting person id to return (used to list a range of persons).
in: query
required: false
type: string
- name: top
description: >-
Number of persons to return starting with the person id indicated by
the 'start' parameter.
in: query
required: false
type: integer
minimum: 1
maximum: 1000
produces:
- application/json
responses:
'200':
description: >-
A successful call returns an array of person information that belong
to the person group.
schema:
$ref: '#/definitions/Persons'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
List persons in person group:
$ref: ./examples/ListPersonGroupPersons.json
summary: Microsoft Azure Get Persongroups Persongroupid Persons
tags:
- Persongroups
/persongroups/{personGroupId}/persons/{personId}:
delete:
description: >-
Delete an existing person from a person group. The persistedFaceId,
userData, person name and face feature in the person entry will all be
deleted.
operationId: microsoftAzurePersongrouppersonDelete
parameters:
- $ref: '#/parameters/personGroupId'
- $ref: '#/parameters/personId'
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Delete an existing person example:
$ref: ./examples/DeletePersonGroupPerson.json
summary: Microsoft Azure Delete Persongroups Persongroupid Persons Personid
tags:
- Persongroups
get:
description: >-
Retrieve a person's information, including registered persisted faces,
name and userData.
operationId: microsoftAzurePersongrouppersonGet
parameters:
- $ref: '#/parameters/personGroupId'
- $ref: '#/parameters/personId'
produces:
- application/json
responses:
'200':
description: A successful call returns the person's information.
schema:
$ref: '#/definitions/Person'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Get person example:
$ref: ./examples/GetPersonGroupPerson.json
summary: Microsoft Azure Get Persongroups Persongroupid Persons Personid
tags:
- Persongroups
patch:
description: Update name or userData of a person.
operationId: microsoftAzurePersongrouppersonUpdate
parameters:
- $ref: '#/parameters/personGroupId'
- $ref: '#/parameters/personId'
- name: body
description: Request body for person update operation.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/NameAndUserDataContract'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Update person example:
$ref: ./examples/UpdatePersonGroupPerson.json
summary: Microsoft Azure Patch Persongroups Persongroupid Persons Personid
tags:
- Persongroups
/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}:
delete:
description: >-
Delete a face from a person in a person group by specified
personGroupId, personId and persistedFaceId.<br> Adding/deleting faces
to/from a same person will be processed sequentially. Adding/deleting
faces to/from different persons are processed in parallel.
operationId: microsoftAzurePersongrouppersonDeleteface
parameters:
- $ref: '#/parameters/personGroupId'
- $ref: '#/parameters/personId'
- $ref: '#/parameters/persistedFaceId'
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Delete face from person example:
$ref: ./examples/DeletePersonGroupPersonFace.json
summary: >-
Microsoft Azure Delete Persongroups Persongroupid Persons Personid Persistedfaces Persistedfaceid
tags:
- Persongroups
get:
description: >-
Retrieve information about a persisted face (specified by
persistedFaceId, personId and its belonging personGroupId).
operationId: microsoftAzurePersongrouppersonGetface
parameters:
- $ref: '#/parameters/personGroupId'
- $ref: '#/parameters/personId'
- $ref: '#/parameters/persistedFaceId'
produces:
- application/json
responses:
'200':
description: >-
A successful call returns target persisted face's information
(persistedFaceId and userData).
schema:
$ref: '#/definitions/PersistedFace'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Get persisted face example:
$ref: ./examples/GetPersonGroupPersistedFace.json
summary: >-
Microsoft Azure Get Persongroups Persongroupid Persons Personid Persistedfaces Persistedfaceid
tags:
- Persongroups
patch:
description: >-
Add a face to a person into a person group for face identification or
verification. To deal with an image contains multiple faces, input face
can be specified as an image with a targetFace rectangle. It returns a
persistedFaceId representing the added face. No image will be stored.
Only the extracted face feature will be stored on server until
[PersonGroup PersonFace -
Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/deleteface),
[PersonGroup Person -
Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/delete)
or [PersonGroup -
Delete](https://docs.microsoft.com/rest/api/faceapi/persongroup/delete)
is called.<br> Note persistedFaceId is different from faceId generated
by [Face -
Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl).<br>*
Higher face image quality means better recognition precision. Please
consider high-quality faces: frontal, clear, and face size is 200x200
pixels (100 pixels between eyes) or bigger.<br>* Each person entry can
hold up to 248 faces.<br>* JPEG, PNG, GIF (the first frame), and BMP
format are supported. The allowed image file size is from 1KB to
6MB.<br>* "targetFace" rectangle should contain one face. Zero or
multiple faces will be regarded as an error. If the provided
"targetFace" rectangle is not returned from [Face -
Detect](https://docs.microsoft.com/rest/api/faceapi/face/detectwithurl),
there’s no guarantee to detect and add the face successfully.<br>* Out
of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or
large occlusions will cause failures.<br>* Adding/deleting faces to/from
a same person will be processed sequentially. Adding/deleting faces
to/from different persons are processed in parallel.
operationId: microsoftAzurePersongrouppersonUpdateface
parameters:
- $ref: '#/parameters/personGroupId'
- $ref: '#/parameters/personId'
- $ref: '#/parameters/persistedFaceId'
- name: body
description: Request body for updating persisted face.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/UpdateFaceRequest'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Update person face example:
$ref: ./examples/UpdatePersonGroupPersonFace.json
summary: >-
Microsoft Azure Patch Persongroups Persongroupid Persons Personid Persistedfaces Persistedfaceid
tags:
- Persongroups
/persongroups/{personGroupId}:
put:
description: >-
Create a new person group with specified personGroupId, name,
user-provided userData and recognitionModel.<br> A person group is the
container of the uploaded person data, including face recognition
features.<br> After creation, use [PersonGroup Person -
Create](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/create)
to add persons into the group, and then call [PersonGroup -
Train](https://docs.microsoft.com/rest/api/faceapi/persongroup/train) to
get this group ready for [Face -
Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify).<br>
No image will be stored. Only the person's extracted face features and
userData will be stored on server until [PersonGroup Person -
Delete](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/delete)
or [PersonGroup -
Delete](https://docs.microsoft.com/rest/api/faceapi/persongroup/delete)
is called.<br>'recognitionModel' should be specified to associate with
this person group. The default value for 'recognitionModel' is
'recognition_01', if the latest model needed, please explicitly specify
the model you need in this parameter. New faces that are added to an
existing person group will use the recognition model that's already
associated with the collection. Existing face features in a person group
can't be updated to features extracted by another version of recognition
model.<br><br>Person group quota:<br>* Free-tier subscription quota:
1,000 person groups. Each holds up to 1,000 persons.<br>* S0-tier
subscription quota: 1,000,000 person groups. Each holds up to 10,000
persons.<br>* to handle larger scale face identification problem, please
consider using
[LargePersonGroup](https://docs.microsoft.com/rest/api/faceapi/largepersongroup).
operationId: microsoftAzurePersongroupCreate
parameters:
- $ref: '#/parameters/personGroupId'
- name: body
description: Request body for creating new person group.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/MetaDataContract'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Create new person group example:
$ref: ./examples/CreateNewPersonGroup.json
summary: Microsoft Azure Put Persongroups Persongroupid
tags:
- Persongroups
delete:
description: >-
Delete an existing person group. Persisted face features of all people
in the person group will also be deleted.
operationId: microsoftAzurePersongroupDelete
parameters:
- $ref: '#/parameters/personGroupId'
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Delete a person group example:
$ref: ./examples/DeletePersonGroup.json
summary: Microsoft Azure Delete Persongroups Persongroupid
tags:
- Persongroups
get:
description: >-
Retrieve person group name, userData and recognitionModel. To get person
information under this personGroup, use [PersonGroup Person -
List](https://docs.microsoft.com/rest/api/faceapi/persongroupperson/list).
operationId: microsoftAzurePersongroupGet
parameters:
- $ref: '#/parameters/personGroupId'
- $ref: '#/parameters/returnRecognitionModel'
responses:
'200':
description: A successful call returns the person group's information.
schema:
$ref: '#/definitions/PersonGroup'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
produces:
- application/json
x-ms-examples:
Get person group example:
$ref: ./examples/GetPersonGroup.json
summary: Microsoft Azure Get Persongroups Persongroupid
tags:
- Persongroups
patch:
description: >-
Update an existing person group's display name and userData. The
properties which does not appear in request body will not be updated.
operationId: microsoftAzurePersongroupUpdate
parameters:
- $ref: '#/parameters/personGroupId'
- name: body
description: Request body for updating person group.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/NameAndUserDataContract'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Update person group example:
$ref: ./examples/UpdatePersonGroup.json
summary: Microsoft Azure Patch Persongroups Persongroupid
tags:
- Persongroups
/persongroups/{personGroupId}/training:
get:
description: Retrieve the training status of a person group (completed or ongoing).
operationId: microsoftAzurePersongroupGettrainingstatus
parameters:
- $ref: '#/parameters/personGroupId'
responses:
'200':
description: A successful call returns the person group's training status.
schema:
$ref: '#/definitions/TrainingStatus'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
produces:
- application/json
x-ms-examples:
Get person group's training status example:
$ref: ./examples/GetPersonGroupTrainingStatus.json
summary: Microsoft Azure Get Persongroups Persongroupid Training
tags:
- Persongroups
/persongroups:
get:
description: >-
List person groups’ personGroupId, name, userData and
recognitionModel.<br>* Person groups are stored in alphabetical order of
personGroupId.<br>* "start" parameter (string, optional) is a
user-provided personGroupId value that returned entries have larger ids
by string comparison. "start" set to empty to indicate return from the
first item.<br>* "top" parameter (int, optional) specifies the number of
entries to return. A maximal of 1000 entries can be returned in one
call. To fetch more, you can specify "start" with the last returned
entry’s Id of the current call.<br><br>For example, total 5 person
groups: "group1", ..., "group5".<br> "start=&top=" will return all 5
groups.<br> "start=&top=2" will return "group1", "group2".<br>
"start=group2&top=3" will return "group3", "group4", "group5".<br>
operationId: microsoftAzurePersongroupList
parameters:
- name: start
in: query
required: false
description: >-
List person groups from the least personGroupId greater than the
"start".
type: string
maxLength: 64
- name: top
in: query
required: false
description: The number of person groups to list.
type: integer
minimum: 1
maximum: 1000
default: 1000
- $ref: '#/parameters/returnRecognitionModel'
produces:
- application/json
responses:
'200':
description: >-
A successful call returns an array of person groups and their
information.
schema:
$ref: '#/definitions/PersonGroups'
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
List person groups example:
$ref: ./examples/ListPersonGroups.json
summary: Microsoft Azure Get Persongroups
tags:
- Persongroups
/persongroups/{personGroupId}/train:
post:
description: >-
Queue a person group training task, the training task may not be started
immediately.
operationId: microsoftAzurePersongroupTrain
parameters:
- $ref: '#/parameters/personGroupId'
produces:
- application/json
responses:
'202':
description: The training task was queued successfully.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Queue person group training:
$ref: ./examples/QueuePersonGroupTraining.json
summary: Microsoft Azure Post Persongroups Persongroupid Train
tags:
- Persongroups
/facelists/{faceListId}:
put:
description: >-
Create an empty face list with user-specified faceListId, name, an
optional userData and recognitionModel. Up to 64 face lists are allowed
in one subscription.<br> Face list is a list of faces, up to 1,000
faces, and used by [Face - Find
Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar).<br>
After creation, user should use [FaceList - Add
Face](https://docs.microsoft.com/rest/api/faceapi/facelist/addfacefromurl)
to import the faces. No image will be stored. Only the extracted face
features are stored on server until [FaceList -
Delete](https://docs.microsoft.com/rest/api/faceapi/facelist/delete) is
called.<br> Find Similar is used for scenario like finding
celebrity-like faces, similar face filtering, or as a light way face
identification. But if the actual use is to identify person, please use
[PersonGroup](https://docs.microsoft.com/rest/api/faceapi/persongroup) /
[LargePersonGroup](https://docs.microsoft.com/rest/api/faceapi/largepersongroup)
and [Face -
Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify).<br>
Please consider
[LargeFaceList](https://docs.microsoft.com/rest/api/faceapi/largefacelist)
when the face number is large. It can support up to 1,000,000
faces.<br>'recognitionModel' should be specified to associate with this
face list. The default value for 'recognitionModel' is 'recognition_01',
if the latest model needed, please explicitly specify the model you need
in this parameter. New faces that are added to an existing face list
will use the recognition model that's already associated with the
collection. Existing face features in a face list can't be updated to
features extracted by another version of recognition model.<br>Please
Refer to [Specify a face recognition
model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).
operationId: microsoftAzureFacelistCreate
parameters:
- $ref: '#/parameters/faceListId'
- name: body
description: Request body for creating a face list.
in: body
required: true
x-ms-client-flatten: true
schema:
$ref: '#/definitions/MetaDataContract'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: A successful call returns an empty response body.
default:
description: Error response.
schema:
$ref: '#/definitions/APIError'
x-ms-examples:
Create new face list example:
$ref: ./examples/CreateNewFaceList.json
summary: Microsoft Azure Put Facelists Facelistid
tags:
- Facelists
get:
description: >-
Retrieve a face list’s faceListId, name, userData, recognitionModel and
faces in the face list.<br>
operationId: microsoftAzureFacelistGet
parameters:
-
# --- truncated at 32 KB (194 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/face-client-openapi-original.yml