diff --git a/profiles/latest/cognitiveservices/face/models.go b/profiles/latest/cognitiveservices/face/models.go
index cfc5cb1cc981..561377d781ba 100644
--- a/profiles/latest/cognitiveservices/face/models.go
+++ b/profiles/latest/cognitiveservices/face/models.go
@@ -117,6 +117,13 @@ const (
Succeeded OperationStatusType = original.Succeeded
)
+type RecognitionModel = original.RecognitionModel
+
+const (
+ Recognition01 RecognitionModel = original.Recognition01
+ Recognition02 RecognitionModel = original.Recognition02
+)
+
type SnapshotApplyMode = original.SnapshotApplyMode
const (
@@ -183,6 +190,7 @@ type ListPersonGroup = original.ListPersonGroup
type ListSimilarFace = original.ListSimilarFace
type ListSnapshot = original.ListSnapshot
type Makeup = original.Makeup
+type MetaDataContract = original.MetaDataContract
type NameAndUserDataContract = original.NameAndUserDataContract
type Noise = original.Noise
type Occlusion = original.Occlusion
@@ -264,6 +272,9 @@ func PossibleNoiseLevelValues() []NoiseLevel {
func PossibleOperationStatusTypeValues() []OperationStatusType {
return original.PossibleOperationStatusTypeValues()
}
+func PossibleRecognitionModelValues() []RecognitionModel {
+ return original.PossibleRecognitionModelValues()
+}
func PossibleSnapshotApplyModeValues() []SnapshotApplyMode {
return original.PossibleSnapshotApplyModeValues()
}
diff --git a/profiles/preview/cognitiveservices/face/models.go b/profiles/preview/cognitiveservices/face/models.go
index 636de6d4386f..88f2619c3e8f 100644
--- a/profiles/preview/cognitiveservices/face/models.go
+++ b/profiles/preview/cognitiveservices/face/models.go
@@ -117,6 +117,13 @@ const (
Succeeded OperationStatusType = original.Succeeded
)
+type RecognitionModel = original.RecognitionModel
+
+const (
+ Recognition01 RecognitionModel = original.Recognition01
+ Recognition02 RecognitionModel = original.Recognition02
+)
+
type SnapshotApplyMode = original.SnapshotApplyMode
const (
@@ -183,6 +190,7 @@ type ListPersonGroup = original.ListPersonGroup
type ListSimilarFace = original.ListSimilarFace
type ListSnapshot = original.ListSnapshot
type Makeup = original.Makeup
+type MetaDataContract = original.MetaDataContract
type NameAndUserDataContract = original.NameAndUserDataContract
type Noise = original.Noise
type Occlusion = original.Occlusion
@@ -264,6 +272,9 @@ func PossibleNoiseLevelValues() []NoiseLevel {
func PossibleOperationStatusTypeValues() []OperationStatusType {
return original.PossibleOperationStatusTypeValues()
}
+func PossibleRecognitionModelValues() []RecognitionModel {
+ return original.PossibleRecognitionModelValues()
+}
func PossibleSnapshotApplyModeValues() []SnapshotApplyMode {
return original.PossibleSnapshotApplyModeValues()
}
diff --git a/services/cognitiveservices/v1.0/face/face.go b/services/cognitiveservices/v1.0/face/face.go
index 52422dbe2ab4..2a5b138526ed 100644
--- a/services/cognitiveservices/v1.0/face/face.go
+++ b/services/cognitiveservices/v1.0/face/face.go
@@ -48,7 +48,13 @@ func NewClient(endpoint string) Client {
// string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose,
// smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational
// and time cost.
-func (client Client) DetectWithStream(ctx context.Context, imageParameter io.ReadCloser, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType) (result ListDetectedFace, err error) {
+// recognitionModel - name of recognition model. Recognition model is used when the face features are extracted
+// and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be
+// provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The
+// default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client Client) DetectWithStream(ctx context.Context, imageParameter io.ReadCloser, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType, recognitionModel RecognitionModel, returnRecognitionModel *bool) (result ListDetectedFace, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/Client.DetectWithStream")
defer func() {
@@ -59,7 +65,7 @@ func (client Client) DetectWithStream(ctx context.Context, imageParameter io.Rea
tracing.EndSpan(ctx, sc, err)
}()
}
- req, err := client.DetectWithStreamPreparer(ctx, imageParameter, returnFaceID, returnFaceLandmarks, returnFaceAttributes)
+ req, err := client.DetectWithStreamPreparer(ctx, imageParameter, returnFaceID, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.Client", "DetectWithStream", nil, "Failure preparing request")
return
@@ -81,7 +87,7 @@ func (client Client) DetectWithStream(ctx context.Context, imageParameter io.Rea
}
// DetectWithStreamPreparer prepares the DetectWithStream request.
-func (client Client) DetectWithStreamPreparer(ctx context.Context, imageParameter io.ReadCloser, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType) (*http.Request, error) {
+func (client Client) DetectWithStreamPreparer(ctx context.Context, imageParameter io.ReadCloser, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType, recognitionModel RecognitionModel, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -100,6 +106,16 @@ func (client Client) DetectWithStreamPreparer(ctx context.Context, imageParamete
if returnFaceAttributes != nil && len(returnFaceAttributes) > 0 {
queryParameters["returnFaceAttributes"] = autorest.Encode("query", returnFaceAttributes, ",")
}
+ if len(string(recognitionModel)) > 0 {
+ queryParameters["recognitionModel"] = autorest.Encode("query", recognitionModel)
+ } else {
+ queryParameters["recognitionModel"] = autorest.Encode("query", "recognition_01")
+ }
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
preparer := autorest.CreatePreparer(
autorest.AsContentType("application/octet-stream"),
@@ -131,8 +147,33 @@ func (client Client) DetectWithStreamResponder(resp *http.Response) (result List
return
}
-// DetectWithURL detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and
-// attributes.
+// DetectWithURL detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and
+// attributes.
+// * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile,
+// facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise.
+// * The extracted face feature, instead of the actual image, will be stored on server. The faceId is an identifier of
+// the face feature and will be used in [Face -
+// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face -
+// Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find
+// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after
+// the detection call.
+// * Higher face image quality means better detection and recognition precision. Please consider high-quality faces:
+// frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
+// * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
+// * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces,
+// please try to enlarge the input image.
+// * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small.
+// * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g.
+// exceptionally large face angles (head-pose) or being occluded, or wrong image orientation.
+// * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories,
+// blur, exposure and noise) may not be perfectly accurate. HeadPose's pitch value is a reserved field and will always
+// return 0.
+// * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are
+// needed, please specify the recognition model with 'recognitionModel' parameter. The default value for
+// 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this
+// parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More
+// details, please refer to [How to specify a recognition
+// model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model)
// Parameters:
// imageURL - a JSON document with a URL pointing to the image that is to be analyzed.
// returnFaceID - a value indicating whether the operation should return faceIds of detected faces.
@@ -142,7 +183,13 @@ func (client Client) DetectWithStreamResponder(resp *http.Response) (result List
// string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose,
// smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational
// and time cost.
-func (client Client) DetectWithURL(ctx context.Context, imageURL ImageURL, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType) (result ListDetectedFace, err error) {
+// recognitionModel - name of recognition model. Recognition model is used when the face features are extracted
+// and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be
+// provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The
+// default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client Client) DetectWithURL(ctx context.Context, imageURL ImageURL, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType, recognitionModel RecognitionModel, returnRecognitionModel *bool) (result ListDetectedFace, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/Client.DetectWithURL")
defer func() {
@@ -159,7 +206,7 @@ func (client Client) DetectWithURL(ctx context.Context, imageURL ImageURL, retur
return result, validation.NewError("face.Client", "DetectWithURL", err.Error())
}
- req, err := client.DetectWithURLPreparer(ctx, imageURL, returnFaceID, returnFaceLandmarks, returnFaceAttributes)
+ req, err := client.DetectWithURLPreparer(ctx, imageURL, returnFaceID, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.Client", "DetectWithURL", nil, "Failure preparing request")
return
@@ -181,7 +228,7 @@ func (client Client) DetectWithURL(ctx context.Context, imageURL ImageURL, retur
}
// DetectWithURLPreparer prepares the DetectWithURL request.
-func (client Client) DetectWithURLPreparer(ctx context.Context, imageURL ImageURL, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType) (*http.Request, error) {
+func (client Client) DetectWithURLPreparer(ctx context.Context, imageURL ImageURL, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []AttributeType, recognitionModel RecognitionModel, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -200,6 +247,16 @@ func (client Client) DetectWithURLPreparer(ctx context.Context, imageURL ImageUR
if returnFaceAttributes != nil && len(returnFaceAttributes) > 0 {
queryParameters["returnFaceAttributes"] = autorest.Encode("query", returnFaceAttributes, ",")
}
+ if len(string(recognitionModel)) > 0 {
+ queryParameters["recognitionModel"] = autorest.Encode("query", recognitionModel)
+ } else {
+ queryParameters["recognitionModel"] = autorest.Encode("query", "recognition_01")
+ }
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
preparer := autorest.CreatePreparer(
autorest.AsContentType("application/json; charset=utf-8"),
@@ -231,8 +288,22 @@ func (client Client) DetectWithURLResponder(resp *http.Response) (result ListDet
return
}
-// FindSimilar given query face's faceId, find the similar-looking faces from a faceId array, a face list or a large
-// face list.
+// FindSimilar 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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours
+// after creation. A "faceListId" is created by [FaceList -
+// Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds
+// that will not expire. And a "largeFaceListId" is created by [LargeFaceList -
+// Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds
+// that will also not expire. Depending on the input the returned similar faces list contains faceIds or
+// persistedFaceIds ranked by similarity.
+//
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.
+//
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.
// Parameters:
// body - request body for Find Similar.
func (client Client) FindSimilar(ctx context.Context, body FindSimilarRequest) (result ListSimilarFace, err error) {
@@ -322,7 +393,16 @@ func (client Client) FindSimilarResponder(resp *http.Response) (result ListSimil
return
}
-// Group divide candidate faces into groups based on face similarity.
+// Group divide candidate faces into groups based on face similarity.
+// * 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.
+// * 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.
+// * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face -
+// Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate
+// faces.
+// * The 'recognitionModel' associated with the query faces' faceIds should be the same.
// Parameters:
// body - request body for grouping.
func (client Client) Group(ctx context.Context, body GroupRequest) (result GroupResult, err error) {
@@ -401,6 +481,26 @@ func (client Client) GroupResponder(resp *http.Response) (result GroupResult, er
// Identify 1-to-many identification to find the closest matches of the specific query person face from a person group
// or large person group.
+//
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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup -
+// Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4).
+//
+//
+// Remarks:
+// * The algorithm allows more than one face to be identified independently at the same request, but no more than 10
+// faces.
+// * Each person in the person group/large person group could have more than one face, but no more than 248 faces.
+// * 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.
+// * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is
+// identified, the returned candidates will be an empty array.
+// * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you
+// need to find similar faces from a face list/large face list instead of a person group/large person group.
+// * 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.
// Parameters:
// body - request body for identify operation.
func (client Client) Identify(ctx context.Context, body IdentifyRequest) (result ListIdentifyResult, err error) {
@@ -490,6 +590,13 @@ func (client Client) IdentifyResponder(resp *http.Response) (result ListIdentify
}
// VerifyFaceToFace verify whether two faces belong to a same person or whether one face belongs to a person.
+//
+// Remarks:
+// * 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.
+// * For the scenarios that are sensitive to accuracy please make your own judgment.
+// * 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.
// Parameters:
// body - request body for face to face verification.
func (client Client) VerifyFaceToFace(ctx context.Context, body VerifyFaceToFaceRequest) (result VerifyResult, err error) {
diff --git a/services/cognitiveservices/v1.0/face/faceapi/interfaces.go b/services/cognitiveservices/v1.0/face/faceapi/interfaces.go
index a25d6d6cbe10..fc2c52ae36bd 100644
--- a/services/cognitiveservices/v1.0/face/faceapi/interfaces.go
+++ b/services/cognitiveservices/v1.0/face/faceapi/interfaces.go
@@ -27,8 +27,8 @@ import (
// ClientAPI contains the set of methods on the Client type.
type ClientAPI interface {
- DetectWithStream(ctx context.Context, imageParameter io.ReadCloser, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []face.AttributeType) (result face.ListDetectedFace, err error)
- DetectWithURL(ctx context.Context, imageURL face.ImageURL, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []face.AttributeType) (result face.ListDetectedFace, err error)
+ DetectWithStream(ctx context.Context, imageParameter io.ReadCloser, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []face.AttributeType, recognitionModel face.RecognitionModel, returnRecognitionModel *bool) (result face.ListDetectedFace, err error)
+ DetectWithURL(ctx context.Context, imageURL face.ImageURL, returnFaceID *bool, returnFaceLandmarks *bool, returnFaceAttributes []face.AttributeType, recognitionModel face.RecognitionModel, returnRecognitionModel *bool) (result face.ListDetectedFace, err error)
FindSimilar(ctx context.Context, body face.FindSimilarRequest) (result face.ListSimilarFace, err error)
Group(ctx context.Context, body face.GroupRequest) (result face.GroupResult, err error)
Identify(ctx context.Context, body face.IdentifyRequest) (result face.ListIdentifyResult, err error)
@@ -56,11 +56,11 @@ var _ PersonGroupPersonClientAPI = (*face.PersonGroupPersonClient)(nil)
// PersonGroupClientAPI contains the set of methods on the PersonGroupClient type.
type PersonGroupClientAPI interface {
- Create(ctx context.Context, personGroupID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
+ Create(ctx context.Context, personGroupID string, body face.MetaDataContract) (result autorest.Response, err error)
Delete(ctx context.Context, personGroupID string) (result autorest.Response, err error)
- Get(ctx context.Context, personGroupID string) (result face.PersonGroup, err error)
+ Get(ctx context.Context, personGroupID string, returnRecognitionModel *bool) (result face.PersonGroup, err error)
GetTrainingStatus(ctx context.Context, personGroupID string) (result face.TrainingStatus, err error)
- List(ctx context.Context, start string, top *int32) (result face.ListPersonGroup, err error)
+ List(ctx context.Context, start string, top *int32, returnRecognitionModel *bool) (result face.ListPersonGroup, err error)
Train(ctx context.Context, personGroupID string) (result autorest.Response, err error)
Update(ctx context.Context, personGroupID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
}
@@ -71,11 +71,11 @@ var _ PersonGroupClientAPI = (*face.PersonGroupClient)(nil)
type ListClientAPI interface {
AddFaceFromStream(ctx context.Context, faceListID string, imageParameter io.ReadCloser, userData string, targetFace []int32) (result face.PersistedFace, err error)
AddFaceFromURL(ctx context.Context, faceListID string, imageURL face.ImageURL, userData string, targetFace []int32) (result face.PersistedFace, err error)
- Create(ctx context.Context, faceListID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
+ Create(ctx context.Context, faceListID string, body face.MetaDataContract) (result autorest.Response, err error)
Delete(ctx context.Context, faceListID string) (result autorest.Response, err error)
DeleteFace(ctx context.Context, faceListID string, persistedFaceID uuid.UUID) (result autorest.Response, err error)
- Get(ctx context.Context, faceListID string) (result face.List, err error)
- List(ctx context.Context) (result face.ListList, err error)
+ Get(ctx context.Context, faceListID string, returnRecognitionModel *bool) (result face.List, err error)
+ List(ctx context.Context, returnRecognitionModel *bool) (result face.ListList, err error)
Update(ctx context.Context, faceListID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
}
@@ -99,11 +99,11 @@ var _ LargePersonGroupPersonClientAPI = (*face.LargePersonGroupPersonClient)(nil
// LargePersonGroupClientAPI contains the set of methods on the LargePersonGroupClient type.
type LargePersonGroupClientAPI interface {
- Create(ctx context.Context, largePersonGroupID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
+ Create(ctx context.Context, largePersonGroupID string, body face.MetaDataContract) (result autorest.Response, err error)
Delete(ctx context.Context, largePersonGroupID string) (result autorest.Response, err error)
- Get(ctx context.Context, largePersonGroupID string) (result face.LargePersonGroup, err error)
+ Get(ctx context.Context, largePersonGroupID string, returnRecognitionModel *bool) (result face.LargePersonGroup, err error)
GetTrainingStatus(ctx context.Context, largePersonGroupID string) (result face.TrainingStatus, err error)
- List(ctx context.Context, start string, top *int32) (result face.ListLargePersonGroup, err error)
+ List(ctx context.Context, start string, top *int32, returnRecognitionModel *bool) (result face.ListLargePersonGroup, err error)
Train(ctx context.Context, largePersonGroupID string) (result autorest.Response, err error)
Update(ctx context.Context, largePersonGroupID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
}
@@ -114,13 +114,13 @@ var _ LargePersonGroupClientAPI = (*face.LargePersonGroupClient)(nil)
type LargeFaceListClientAPI interface {
AddFaceFromStream(ctx context.Context, largeFaceListID string, imageParameter io.ReadCloser, userData string, targetFace []int32) (result face.PersistedFace, err error)
AddFaceFromURL(ctx context.Context, largeFaceListID string, imageURL face.ImageURL, userData string, targetFace []int32) (result face.PersistedFace, err error)
- Create(ctx context.Context, largeFaceListID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
+ Create(ctx context.Context, largeFaceListID string, body face.MetaDataContract) (result autorest.Response, err error)
Delete(ctx context.Context, largeFaceListID string) (result autorest.Response, err error)
DeleteFace(ctx context.Context, largeFaceListID string, persistedFaceID uuid.UUID) (result autorest.Response, err error)
- Get(ctx context.Context, largeFaceListID string) (result face.LargeFaceList, err error)
+ Get(ctx context.Context, largeFaceListID string, returnRecognitionModel *bool) (result face.LargeFaceList, err error)
GetFace(ctx context.Context, largeFaceListID string, persistedFaceID uuid.UUID) (result face.PersistedFace, err error)
GetTrainingStatus(ctx context.Context, largeFaceListID string) (result face.TrainingStatus, err error)
- List(ctx context.Context) (result face.ListLargeFaceList, err error)
+ List(ctx context.Context, returnRecognitionModel *bool) (result face.ListLargeFaceList, err error)
ListFaces(ctx context.Context, largeFaceListID string, start string, top *int32) (result face.ListPersistedFace, err error)
Train(ctx context.Context, largeFaceListID string) (result autorest.Response, err error)
Update(ctx context.Context, largeFaceListID string, body face.NameAndUserDataContract) (result autorest.Response, err error)
diff --git a/services/cognitiveservices/v1.0/face/largefacelist.go b/services/cognitiveservices/v1.0/face/largefacelist.go
index b25d04dd7c7b..bc421c8a514d 100644
--- a/services/cognitiveservices/v1.0/face/largefacelist.go
+++ b/services/cognitiveservices/v1.0/face/largefacelist.go
@@ -238,11 +238,34 @@ func (client LargeFaceListClient) AddFaceFromURLResponder(resp *http.Response) (
return
}
-// Create create an empty large face list. Up to 64 large face lists are allowed to exist in one subscription.
+// Create create an empty large face list with user-specified largeFaceListId, name, an optional userData and
+// recognitionModel.
+//
Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find
+// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
+//
After creation, user should use [LargeFaceList Face -
+// Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and
+// [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it
+// ready for [Face - FindSimilar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). Faces
+// are stored on server until [LargeFaceList -
+// Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called.
+//
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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) /
+// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face -
+// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
+//
+// * Free-tier subscription quota: 64 large face lists.
+// * S0-tier subscription quota: 1,000,000 large face lists.
+//
+// 'recognitionModel' should be specified to associate with this large 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 large face list will use the recognition model that's
+// already associated with the collection. Existing face features in a large face list can't be updated to features
+// extracted by another version of recognition model.
// Parameters:
// largeFaceListID - id referencing a particular large face list.
// body - request body for creating a large face list.
-func (client LargeFaceListClient) Create(ctx context.Context, largeFaceListID string, body NameAndUserDataContract) (result autorest.Response, err error) {
+func (client LargeFaceListClient) Create(ctx context.Context, largeFaceListID string, body MetaDataContract) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/LargeFaceListClient.Create")
defer func() {
@@ -256,12 +279,7 @@ func (client LargeFaceListClient) Create(ctx context.Context, largeFaceListID st
if err := validation.Validate([]validation.Validation{
{TargetValue: largeFaceListID,
Constraints: []validation.Constraint{{Target: "largeFaceListID", Name: validation.MaxLength, Rule: 64, Chain: nil},
- {Target: "largeFaceListID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}},
- {TargetValue: body,
- Constraints: []validation.Constraint{{Target: "body.Name", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.Name", Name: validation.MaxLength, Rule: 128, Chain: nil}}},
- {Target: "body.UserData", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.UserData", Name: validation.MaxLength, Rule: 16384, Chain: nil}}}}}}); err != nil {
+ {Target: "largeFaceListID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}}}); err != nil {
return result, validation.NewError("face.LargeFaceListClient", "Create", err.Error())
}
@@ -287,7 +305,7 @@ func (client LargeFaceListClient) Create(ctx context.Context, largeFaceListID st
}
// CreatePreparer prepares the Create request.
-func (client LargeFaceListClient) CreatePreparer(ctx context.Context, largeFaceListID string, body NameAndUserDataContract) (*http.Request, error) {
+func (client LargeFaceListClient) CreatePreparer(ctx context.Context, largeFaceListID string, body MetaDataContract) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -484,10 +502,12 @@ func (client LargeFaceListClient) DeleteFaceResponder(resp *http.Response) (resu
return
}
-// Get retrieve a large face list's information.
+// Get retrieve a large face list’s largeFaceListId, name, userData and recognitionModel.
// Parameters:
// largeFaceListID - id referencing a particular large face list.
-func (client LargeFaceListClient) Get(ctx context.Context, largeFaceListID string) (result LargeFaceList, err error) {
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client LargeFaceListClient) Get(ctx context.Context, largeFaceListID string, returnRecognitionModel *bool) (result LargeFaceList, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/LargeFaceListClient.Get")
defer func() {
@@ -505,7 +525,7 @@ func (client LargeFaceListClient) Get(ctx context.Context, largeFaceListID strin
return result, validation.NewError("face.LargeFaceListClient", "Get", err.Error())
}
- req, err := client.GetPreparer(ctx, largeFaceListID)
+ req, err := client.GetPreparer(ctx, largeFaceListID, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.LargeFaceListClient", "Get", nil, "Failure preparing request")
return
@@ -527,7 +547,7 @@ func (client LargeFaceListClient) Get(ctx context.Context, largeFaceListID strin
}
// GetPreparer prepares the Get request.
-func (client LargeFaceListClient) GetPreparer(ctx context.Context, largeFaceListID string) (*http.Request, error) {
+func (client LargeFaceListClient) GetPreparer(ctx context.Context, largeFaceListID string, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -536,10 +556,18 @@ func (client LargeFaceListClient) GetPreparer(ctx context.Context, largeFaceList
"largeFaceListId": autorest.Encode("path", largeFaceListID),
}
+ queryParameters := map[string]interface{}{}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
+
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
- autorest.WithPathParameters("/largefacelists/{largeFaceListId}", pathParameters))
+ autorest.WithPathParameters("/largefacelists/{largeFaceListId}", pathParameters),
+ autorest.WithQueryParameters(queryParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
@@ -724,9 +752,23 @@ func (client LargeFaceListClient) GetTrainingStatusResponder(resp *http.Response
return
}
-// List retrieve information about all existing large face lists. Only largeFaceListId, name and userData will be
-// returned.
-func (client LargeFaceListClient) List(ctx context.Context) (result ListLargeFaceList, err error) {
+// List list large face lists’ information of largeFaceListId, name, userData and recognitionModel.
+// To get face information inside largeFaceList use [LargeFaceList Face -
+// Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)
+// * Large face lists are stored in alphabetical order of largeFaceListId.
+// * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger
+// ids by string comparison. "start" set to empty to indicate return from the first item.
+// * "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.
+//
+// For example, total 5 large person lists: "list1", ..., "list5".
+//
"start=&top=" will return all 5 lists.
+//
"start=&top=2" will return "list1", "list2".
+//
"start=list2&top=3" will return "list3", "list4", "list5".
+// Parameters:
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client LargeFaceListClient) List(ctx context.Context, returnRecognitionModel *bool) (result ListLargeFaceList, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/LargeFaceListClient.List")
defer func() {
@@ -737,7 +779,7 @@ func (client LargeFaceListClient) List(ctx context.Context) (result ListLargeFac
tracing.EndSpan(ctx, sc, err)
}()
}
- req, err := client.ListPreparer(ctx)
+ req, err := client.ListPreparer(ctx, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.LargeFaceListClient", "List", nil, "Failure preparing request")
return
@@ -759,15 +801,23 @@ func (client LargeFaceListClient) List(ctx context.Context) (result ListLargeFac
}
// ListPreparer prepares the List request.
-func (client LargeFaceListClient) ListPreparer(ctx context.Context) (*http.Request, error) {
+func (client LargeFaceListClient) ListPreparer(ctx context.Context, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
+ queryParameters := map[string]interface{}{}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
+
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
- autorest.WithPath("/largefacelists"))
+ autorest.WithPath("/largefacelists"),
+ autorest.WithQueryParameters(queryParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
diff --git a/services/cognitiveservices/v1.0/face/largepersongroup.go b/services/cognitiveservices/v1.0/face/largepersongroup.go
index 2f59a1519618..6bbddf0f5d36 100644
--- a/services/cognitiveservices/v1.0/face/largepersongroup.go
+++ b/services/cognitiveservices/v1.0/face/largepersongroup.go
@@ -36,11 +36,31 @@ func NewLargePersonGroupClient(endpoint string) LargePersonGroupClient {
return LargePersonGroupClient{New(endpoint)}
}
-// Create create a new large person group with specified largePersonGroupId, name and user-provided userData.
+// Create create a new large person group with user-specified largePersonGroupId, name, an optional userData and
+// recognitionModel.
+//
A large person group is the container of the uploaded person data, including face images and face recognition
+// feature, and up to 1,000,000 people.
+//
After creation, use [LargePersonGroup Person -
+// Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group,
+// and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to
+// get this group ready for [Face -
+// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
+//
The person face, image, and userData will be stored on server until [LargePersonGroup Person -
+// Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup -
+// Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called.
+//
+// * Free-tier subscription quota: 1,000 large person groups.
+// * S0-tier subscription quota: 1,000,000 large person groups.
+//
+// 'recognitionModel' should be specified to associate with this large 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 large person group will use the recognition model that's
+// already associated with the collection. Existing face features in a large person group can't be updated to features
+// extracted by another version of recognition model.
// Parameters:
// largePersonGroupID - id referencing a particular large person group.
// body - request body for creating new large person group.
-func (client LargePersonGroupClient) Create(ctx context.Context, largePersonGroupID string, body NameAndUserDataContract) (result autorest.Response, err error) {
+func (client LargePersonGroupClient) Create(ctx context.Context, largePersonGroupID string, body MetaDataContract) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/LargePersonGroupClient.Create")
defer func() {
@@ -54,12 +74,7 @@ func (client LargePersonGroupClient) Create(ctx context.Context, largePersonGrou
if err := validation.Validate([]validation.Validation{
{TargetValue: largePersonGroupID,
Constraints: []validation.Constraint{{Target: "largePersonGroupID", Name: validation.MaxLength, Rule: 64, Chain: nil},
- {Target: "largePersonGroupID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}},
- {TargetValue: body,
- Constraints: []validation.Constraint{{Target: "body.Name", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.Name", Name: validation.MaxLength, Rule: 128, Chain: nil}}},
- {Target: "body.UserData", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.UserData", Name: validation.MaxLength, Rule: 16384, Chain: nil}}}}}}); err != nil {
+ {Target: "largePersonGroupID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}}}); err != nil {
return result, validation.NewError("face.LargePersonGroupClient", "Create", err.Error())
}
@@ -85,7 +100,7 @@ func (client LargePersonGroupClient) Create(ctx context.Context, largePersonGrou
}
// CreatePreparer prepares the Create request.
-func (client LargePersonGroupClient) CreatePreparer(ctx context.Context, largePersonGroupID string, body NameAndUserDataContract) (*http.Request, error) {
+func (client LargePersonGroupClient) CreatePreparer(ctx context.Context, largePersonGroupID string, body MetaDataContract) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -201,10 +216,15 @@ func (client LargePersonGroupClient) DeleteResponder(resp *http.Response) (resul
return
}
-// Get retrieve the information of a large person group, including its name and userData.
+// Get retrieve the information of a large person group, including its name, userData and recognitionModel. This API
+// returns large person group information only, use [LargePersonGroup Person -
+// List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person
+// information under the large person group.
// Parameters:
// largePersonGroupID - id referencing a particular large person group.
-func (client LargePersonGroupClient) Get(ctx context.Context, largePersonGroupID string) (result LargePersonGroup, err error) {
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client LargePersonGroupClient) Get(ctx context.Context, largePersonGroupID string, returnRecognitionModel *bool) (result LargePersonGroup, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/LargePersonGroupClient.Get")
defer func() {
@@ -222,7 +242,7 @@ func (client LargePersonGroupClient) Get(ctx context.Context, largePersonGroupID
return result, validation.NewError("face.LargePersonGroupClient", "Get", err.Error())
}
- req, err := client.GetPreparer(ctx, largePersonGroupID)
+ req, err := client.GetPreparer(ctx, largePersonGroupID, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.LargePersonGroupClient", "Get", nil, "Failure preparing request")
return
@@ -244,7 +264,7 @@ func (client LargePersonGroupClient) Get(ctx context.Context, largePersonGroupID
}
// GetPreparer prepares the Get request.
-func (client LargePersonGroupClient) GetPreparer(ctx context.Context, largePersonGroupID string) (*http.Request, error) {
+func (client LargePersonGroupClient) GetPreparer(ctx context.Context, largePersonGroupID string, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -253,10 +273,18 @@ func (client LargePersonGroupClient) GetPreparer(ctx context.Context, largePerso
"largePersonGroupId": autorest.Encode("path", largePersonGroupID),
}
+ queryParameters := map[string]interface{}{}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
+
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
- autorest.WithPathParameters("/largepersongroups/{largePersonGroupId}", pathParameters))
+ autorest.WithPathParameters("/largepersongroups/{largePersonGroupId}", pathParameters),
+ autorest.WithQueryParameters(queryParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
@@ -359,11 +387,23 @@ func (client LargePersonGroupClient) GetTrainingStatusResponder(resp *http.Respo
return
}
-// List list large person groups and their information.
+// List list all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.
+// * Large person groups are stored in alphabetical order of largePersonGroupId.
+// * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger
+// ids by string comparison. "start" set to empty to indicate return from the first item.
+// * "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.
+//
+// For example, total 5 large person groups: "group1", ..., "group5".
+//
"start=&top=" will return all 5 groups.
+//
"start=&top=2" will return "group1", "group2".
+//
"start=group2&top=3" will return "group3", "group4", "group5".
// Parameters:
// start - list large person groups from the least largePersonGroupId greater than the "start".
// top - the number of large person groups to list.
-func (client LargePersonGroupClient) List(ctx context.Context, start string, top *int32) (result ListLargePersonGroup, err error) {
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client LargePersonGroupClient) List(ctx context.Context, start string, top *int32, returnRecognitionModel *bool) (result ListLargePersonGroup, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/LargePersonGroupClient.List")
defer func() {
@@ -385,7 +425,7 @@ func (client LargePersonGroupClient) List(ctx context.Context, start string, top
return result, validation.NewError("face.LargePersonGroupClient", "List", err.Error())
}
- req, err := client.ListPreparer(ctx, start, top)
+ req, err := client.ListPreparer(ctx, start, top, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.LargePersonGroupClient", "List", nil, "Failure preparing request")
return
@@ -407,7 +447,7 @@ func (client LargePersonGroupClient) List(ctx context.Context, start string, top
}
// ListPreparer prepares the List request.
-func (client LargePersonGroupClient) ListPreparer(ctx context.Context, start string, top *int32) (*http.Request, error) {
+func (client LargePersonGroupClient) ListPreparer(ctx context.Context, start string, top *int32, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -421,6 +461,11 @@ func (client LargePersonGroupClient) ListPreparer(ctx context.Context, start str
} else {
queryParameters["top"] = autorest.Encode("query", 1000)
}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
preparer := autorest.CreatePreparer(
autorest.AsGet(),
diff --git a/services/cognitiveservices/v1.0/face/list.go b/services/cognitiveservices/v1.0/face/list.go
index 70755ae1bc1f..bca38e62c047 100644
--- a/services/cognitiveservices/v1.0/face/list.go
+++ b/services/cognitiveservices/v1.0/face/list.go
@@ -238,11 +238,29 @@ func (client ListClient) AddFaceFromURLResponder(resp *http.Response) (result Pe
return
}
-// Create create an empty face list. Up to 64 face lists are allowed to exist in one subscription.
+// Create 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.
+//
Face list is a list of faces, up to 1,000 faces, and used by [Face - Find
+// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
+//
After creation, user should use [FaceList - Add
+// Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. Faces are
+// stored on server until [FaceList -
+// Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called.
+//
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](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) /
+// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face -
+// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
+//
Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc)
+// when the face number is large. It can support up to 1,000,000 faces. '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.
// Parameters:
// faceListID - id referencing a particular face list.
// body - request body for creating a face list.
-func (client ListClient) Create(ctx context.Context, faceListID string, body NameAndUserDataContract) (result autorest.Response, err error) {
+func (client ListClient) Create(ctx context.Context, faceListID string, body MetaDataContract) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/ListClient.Create")
defer func() {
@@ -256,12 +274,7 @@ func (client ListClient) Create(ctx context.Context, faceListID string, body Nam
if err := validation.Validate([]validation.Validation{
{TargetValue: faceListID,
Constraints: []validation.Constraint{{Target: "faceListID", Name: validation.MaxLength, Rule: 64, Chain: nil},
- {Target: "faceListID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}},
- {TargetValue: body,
- Constraints: []validation.Constraint{{Target: "body.Name", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.Name", Name: validation.MaxLength, Rule: 128, Chain: nil}}},
- {Target: "body.UserData", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.UserData", Name: validation.MaxLength, Rule: 16384, Chain: nil}}}}}}); err != nil {
+ {Target: "faceListID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}}}); err != nil {
return result, validation.NewError("face.ListClient", "Create", err.Error())
}
@@ -287,7 +300,7 @@ func (client ListClient) Create(ctx context.Context, faceListID string, body Nam
}
// CreatePreparer prepares the Create request.
-func (client ListClient) CreatePreparer(ctx context.Context, faceListID string, body NameAndUserDataContract) (*http.Request, error) {
+func (client ListClient) CreatePreparer(ctx context.Context, faceListID string, body MetaDataContract) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -484,10 +497,12 @@ func (client ListClient) DeleteFaceResponder(resp *http.Response) (result autore
return
}
-// Get retrieve a face list's information.
+// Get retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.
// Parameters:
// faceListID - id referencing a particular face list.
-func (client ListClient) Get(ctx context.Context, faceListID string) (result List, err error) {
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client ListClient) Get(ctx context.Context, faceListID string, returnRecognitionModel *bool) (result List, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/ListClient.Get")
defer func() {
@@ -505,7 +520,7 @@ func (client ListClient) Get(ctx context.Context, faceListID string) (result Lis
return result, validation.NewError("face.ListClient", "Get", err.Error())
}
- req, err := client.GetPreparer(ctx, faceListID)
+ req, err := client.GetPreparer(ctx, faceListID, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.ListClient", "Get", nil, "Failure preparing request")
return
@@ -527,7 +542,7 @@ func (client ListClient) Get(ctx context.Context, faceListID string) (result Lis
}
// GetPreparer prepares the Get request.
-func (client ListClient) GetPreparer(ctx context.Context, faceListID string) (*http.Request, error) {
+func (client ListClient) GetPreparer(ctx context.Context, faceListID string, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -536,10 +551,18 @@ func (client ListClient) GetPreparer(ctx context.Context, faceListID string) (*h
"faceListId": autorest.Encode("path", faceListID),
}
+ queryParameters := map[string]interface{}{}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
+
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
- autorest.WithPathParameters("/facelists/{faceListId}", pathParameters))
+ autorest.WithPathParameters("/facelists/{faceListId}", pathParameters),
+ autorest.WithQueryParameters(queryParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
@@ -563,8 +586,13 @@ func (client ListClient) GetResponder(resp *http.Response) (result List, err err
return
}
-// List retrieve information about all existing face lists. Only faceListId, name and userData will be returned.
-func (client ListClient) List(ctx context.Context) (result ListList, err error) {
+// List list face lists’ faceListId, name, userData and recognitionModel.
+// To get face information inside faceList use [FaceList -
+// Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c)
+// Parameters:
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client ListClient) List(ctx context.Context, returnRecognitionModel *bool) (result ListList, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/ListClient.List")
defer func() {
@@ -575,7 +603,7 @@ func (client ListClient) List(ctx context.Context) (result ListList, err error)
tracing.EndSpan(ctx, sc, err)
}()
}
- req, err := client.ListPreparer(ctx)
+ req, err := client.ListPreparer(ctx, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.ListClient", "List", nil, "Failure preparing request")
return
@@ -597,15 +625,23 @@ func (client ListClient) List(ctx context.Context) (result ListList, err error)
}
// ListPreparer prepares the List request.
-func (client ListClient) ListPreparer(ctx context.Context) (*http.Request, error) {
+func (client ListClient) ListPreparer(ctx context.Context, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
+ queryParameters := map[string]interface{}{}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
+
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
- autorest.WithPath("/facelists"))
+ autorest.WithPath("/facelists"),
+ autorest.WithQueryParameters(queryParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
diff --git a/services/cognitiveservices/v1.0/face/models.go b/services/cognitiveservices/v1.0/face/models.go
index 78cfc6c0b9c2..0e37027331f1 100644
--- a/services/cognitiveservices/v1.0/face/models.go
+++ b/services/cognitiveservices/v1.0/face/models.go
@@ -228,6 +228,21 @@ func PossibleOperationStatusTypeValues() []OperationStatusType {
return []OperationStatusType{Failed, Notstarted, Running, Succeeded}
}
+// RecognitionModel enumerates the values for recognition model.
+type RecognitionModel string
+
+const (
+ // Recognition01 ...
+ Recognition01 RecognitionModel = "recognition_01"
+ // Recognition02 ...
+ Recognition02 RecognitionModel = "recognition_02"
+)
+
+// PossibleRecognitionModelValues returns an array of possible values for the RecognitionModel const type.
+func PossibleRecognitionModelValues() []RecognitionModel {
+ return []RecognitionModel{Recognition01, Recognition02}
+}
+
// SnapshotApplyMode enumerates the values for snapshot apply mode.
type SnapshotApplyMode string
@@ -350,10 +365,12 @@ type Coordinate struct {
// DetectedFace detected Face object.
type DetectedFace struct {
- FaceID *uuid.UUID `json:"faceId,omitempty"`
- FaceRectangle *Rectangle `json:"faceRectangle,omitempty"`
- FaceLandmarks *Landmarks `json:"faceLandmarks,omitempty"`
- FaceAttributes *Attributes `json:"faceAttributes,omitempty"`
+ FaceID *uuid.UUID `json:"faceId,omitempty"`
+ // RecognitionModel - Possible values include: 'Recognition01', 'Recognition02'
+ RecognitionModel RecognitionModel `json:"recognitionModel,omitempty"`
+ FaceRectangle *Rectangle `json:"faceRectangle,omitempty"`
+ FaceLandmarks *Landmarks `json:"faceLandmarks,omitempty"`
+ FaceAttributes *Attributes `json:"faceAttributes,omitempty"`
}
// Emotion properties describing facial emotion in form of confidence ranging from 0 to 1.
@@ -518,6 +535,8 @@ type LargeFaceList struct {
autorest.Response `json:"-"`
// LargeFaceListID - LargeFaceListId of the target large face list.
LargeFaceListID *string `json:"largeFaceListId,omitempty"`
+ // RecognitionModel - Possible values include: 'Recognition01', 'Recognition02'
+ RecognitionModel RecognitionModel `json:"recognitionModel,omitempty"`
// Name - User defined name, maximum length is 128.
Name *string `json:"name,omitempty"`
// UserData - User specified data. Length should not exceed 16KB.
@@ -529,6 +548,8 @@ type LargePersonGroup struct {
autorest.Response `json:"-"`
// LargePersonGroupID - LargePersonGroupId of the target large person groups
LargePersonGroupID *string `json:"largePersonGroupId,omitempty"`
+ // RecognitionModel - Possible values include: 'Recognition01', 'Recognition02'
+ RecognitionModel RecognitionModel `json:"recognitionModel,omitempty"`
// Name - User defined name, maximum length is 128.
Name *string `json:"name,omitempty"`
// UserData - User specified data. Length should not exceed 16KB.
@@ -542,6 +563,8 @@ type List struct {
FaceListID *string `json:"faceListId,omitempty"`
// PersistedFaces - Persisted faces within the face list.
PersistedFaces *[]PersistedFace `json:"persistedFaces,omitempty"`
+ // RecognitionModel - Possible values include: 'Recognition01', 'Recognition02'
+ RecognitionModel RecognitionModel `json:"recognitionModel,omitempty"`
// Name - User defined name, maximum length is 128.
Name *string `json:"name,omitempty"`
// UserData - User specified data. Length should not exceed 16KB.
@@ -616,6 +639,17 @@ type Makeup struct {
LipMakeup *bool `json:"lipMakeup,omitempty"`
}
+// MetaDataContract a combination of user defined name and user specified data and recognition model name
+// for largePersonGroup/personGroup, and largeFaceList/faceList.
+type MetaDataContract struct {
+ // RecognitionModel - Possible values include: 'Recognition01', 'Recognition02'
+ RecognitionModel RecognitionModel `json:"recognitionModel,omitempty"`
+ // Name - User defined name, maximum length is 128.
+ Name *string `json:"name,omitempty"`
+ // UserData - User specified data. Length should not exceed 16KB.
+ UserData *string `json:"userData,omitempty"`
+}
+
// NameAndUserDataContract a combination of user defined name and user specified data for the person,
// largePersonGroup/personGroup, and largeFaceList/faceList.
type NameAndUserDataContract struct {
@@ -686,6 +720,8 @@ type PersonGroup struct {
autorest.Response `json:"-"`
// PersonGroupID - PersonGroupId of the target person group.
PersonGroupID *string `json:"personGroupId,omitempty"`
+ // RecognitionModel - Possible values include: 'Recognition01', 'Recognition02'
+ RecognitionModel RecognitionModel `json:"recognitionModel,omitempty"`
// Name - User defined name, maximum length is 128.
Name *string `json:"name,omitempty"`
// UserData - User specified data. Length should not exceed 16KB.
diff --git a/services/cognitiveservices/v1.0/face/persongroup.go b/services/cognitiveservices/v1.0/face/persongroup.go
index bd21a0a07886..77275f28c30d 100644
--- a/services/cognitiveservices/v1.0/face/persongroup.go
+++ b/services/cognitiveservices/v1.0/face/persongroup.go
@@ -36,11 +36,32 @@ func NewPersonGroupClient(endpoint string) PersonGroupClient {
return PersonGroupClient{New(endpoint)}
}
-// Create create a new person group with specified personGroupId, name and user-provided userData.
+// Create create a new person group with specified personGroupId, name, user-provided userData and recognitionModel.
+//
A person group is the container of the uploaded person data, including face images and face recognition
+// features.
+//
After creation, use [PersonGroup Person -
+// Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group,
+// and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to
+// get this group ready for [Face -
+// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
+//
The person's face, image, and userData will be stored on server until [PersonGroup Person -
+// Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup -
+// Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called.
+//
+// * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons.
+// * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons.
+// * to handle larger scale face identification problem, please consider using
+// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d).
+//
+// '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.
// Parameters:
// personGroupID - id referencing a particular person group.
// body - request body for creating new person group.
-func (client PersonGroupClient) Create(ctx context.Context, personGroupID string, body NameAndUserDataContract) (result autorest.Response, err error) {
+func (client PersonGroupClient) Create(ctx context.Context, personGroupID string, body MetaDataContract) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/PersonGroupClient.Create")
defer func() {
@@ -54,12 +75,7 @@ func (client PersonGroupClient) Create(ctx context.Context, personGroupID string
if err := validation.Validate([]validation.Validation{
{TargetValue: personGroupID,
Constraints: []validation.Constraint{{Target: "personGroupID", Name: validation.MaxLength, Rule: 64, Chain: nil},
- {Target: "personGroupID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}},
- {TargetValue: body,
- Constraints: []validation.Constraint{{Target: "body.Name", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.Name", Name: validation.MaxLength, Rule: 128, Chain: nil}}},
- {Target: "body.UserData", Name: validation.Null, Rule: false,
- Chain: []validation.Constraint{{Target: "body.UserData", Name: validation.MaxLength, Rule: 16384, Chain: nil}}}}}}); err != nil {
+ {Target: "personGroupID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil}}}}); err != nil {
return result, validation.NewError("face.PersonGroupClient", "Create", err.Error())
}
@@ -85,7 +101,7 @@ func (client PersonGroupClient) Create(ctx context.Context, personGroupID string
}
// CreatePreparer prepares the Create request.
-func (client PersonGroupClient) CreatePreparer(ctx context.Context, personGroupID string, body NameAndUserDataContract) (*http.Request, error) {
+func (client PersonGroupClient) CreatePreparer(ctx context.Context, personGroupID string, body MetaDataContract) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -201,10 +217,13 @@ func (client PersonGroupClient) DeleteResponder(resp *http.Response) (result aut
return
}
-// Get retrieve the information of a person group, including its name and userData.
+// Get retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use
+// [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241).
// Parameters:
// personGroupID - id referencing a particular person group.
-func (client PersonGroupClient) Get(ctx context.Context, personGroupID string) (result PersonGroup, err error) {
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client PersonGroupClient) Get(ctx context.Context, personGroupID string, returnRecognitionModel *bool) (result PersonGroup, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/PersonGroupClient.Get")
defer func() {
@@ -222,7 +241,7 @@ func (client PersonGroupClient) Get(ctx context.Context, personGroupID string) (
return result, validation.NewError("face.PersonGroupClient", "Get", err.Error())
}
- req, err := client.GetPreparer(ctx, personGroupID)
+ req, err := client.GetPreparer(ctx, personGroupID, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.PersonGroupClient", "Get", nil, "Failure preparing request")
return
@@ -244,7 +263,7 @@ func (client PersonGroupClient) Get(ctx context.Context, personGroupID string) (
}
// GetPreparer prepares the Get request.
-func (client PersonGroupClient) GetPreparer(ctx context.Context, personGroupID string) (*http.Request, error) {
+func (client PersonGroupClient) GetPreparer(ctx context.Context, personGroupID string, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -253,10 +272,18 @@ func (client PersonGroupClient) GetPreparer(ctx context.Context, personGroupID s
"personGroupId": autorest.Encode("path", personGroupID),
}
+ queryParameters := map[string]interface{}{}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
+
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
- autorest.WithPathParameters("/persongroups/{personGroupId}", pathParameters))
+ autorest.WithPathParameters("/persongroups/{personGroupId}", pathParameters),
+ autorest.WithQueryParameters(queryParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
@@ -359,11 +386,23 @@ func (client PersonGroupClient) GetTrainingStatusResponder(resp *http.Response)
return
}
-// List list person groups and their information.
+// List list person groups’ personGroupId, name, userData and recognitionModel.
+// * Person groups are stored in alphabetical order of personGroupId.
+// * "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.
+// * "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.
+//
+// For example, total 5 person groups: "group1", ..., "group5".
+//
"start=&top=" will return all 5 groups.
+//
"start=&top=2" will return "group1", "group2".
+//
"start=group2&top=3" will return "group3", "group4", "group5".
// Parameters:
// start - list person groups from the least personGroupId greater than the "start".
// top - the number of person groups to list.
-func (client PersonGroupClient) List(ctx context.Context, start string, top *int32) (result ListPersonGroup, err error) {
+// returnRecognitionModel - a value indicating whether the operation should return 'recognitionModel' in
+// response.
+func (client PersonGroupClient) List(ctx context.Context, start string, top *int32, returnRecognitionModel *bool) (result ListPersonGroup, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/PersonGroupClient.List")
defer func() {
@@ -385,7 +424,7 @@ func (client PersonGroupClient) List(ctx context.Context, start string, top *int
return result, validation.NewError("face.PersonGroupClient", "List", err.Error())
}
- req, err := client.ListPreparer(ctx, start, top)
+ req, err := client.ListPreparer(ctx, start, top, returnRecognitionModel)
if err != nil {
err = autorest.NewErrorWithError(err, "face.PersonGroupClient", "List", nil, "Failure preparing request")
return
@@ -407,7 +446,7 @@ func (client PersonGroupClient) List(ctx context.Context, start string, top *int
}
// ListPreparer prepares the List request.
-func (client PersonGroupClient) ListPreparer(ctx context.Context, start string, top *int32) (*http.Request, error) {
+func (client PersonGroupClient) ListPreparer(ctx context.Context, start string, top *int32, returnRecognitionModel *bool) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
@@ -421,6 +460,11 @@ func (client PersonGroupClient) ListPreparer(ctx context.Context, start string,
} else {
queryParameters["top"] = autorest.Encode("query", 1000)
}
+ if returnRecognitionModel != nil {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", *returnRecognitionModel)
+ } else {
+ queryParameters["returnRecognitionModel"] = autorest.Encode("query", false)
+ }
preparer := autorest.CreatePreparer(
autorest.AsGet(),