Partager via

Face Recognition Operations - Find Similar

  • Référence
Service:
Azure AI Services
Version d'API:
v1.2-preview.1

En fonction du faceId du visage de la requête, pour rechercher les visages similaires à partir d’un tableau faceId. Un tableau faceId contient les visages créés par Detect.
En fonction de l’entrée, la liste des visages similaires retournés contient des faceIds ou persistedFaceIds classés par similarité.

La recherche similaire a deux modes de travail, « matchPerson » et « matchFace ». « matchPerson » est le mode par défaut qu’il tente de trouver des visages de la même personne que possible en utilisant des seuils internes de même personne. Il est utile de trouver les autres photos d’une personne connue. Notez qu’une liste vide est retournée si aucun visage ne dépasse les seuils internes. Le mode « matchFace » ignore les seuils de même personne et retourne des visages similaires classés de toute façon, même la similarité est faible. Il peut être utilisé dans les cas comme la recherche de visages de célébrités.

Le « recognitionModel » associé au faceId de requête doit être identique au « recognitionModel » utilisé par le tableau faceId cible.

POST {endpoint}/face/{apiVersion}/findsimilars

Paramètres URI

Nom Dans Obligatoire Type Description
apiVersion
 path True

string

Version de l’API
endpoint
 path True

string

uri

Points de terminaison Cognitive Services pris en charge (protocole et nom d’hôte, par exemple : https://{nom-ressource}.cognitiveservices.azure.com).

Corps de la demande

Nom Obligatoire Type Description
faceId True

string

faceId du visage de la requête. L’utilisateur doit d’abord appeler « Detect » pour obtenir un faceId valide. Notez que ce faceId n’est pas conservé et expire 24 heures après l’appel de détection.
faceIds True

string[]

Tableau de faceIds candidats. Tous sont créés par « Detect » et les faceIds expirent 24 heures après l’appel de détection. Le nombre de faceIds est limité à 1 000.
maxNumOfCandidatesReturned

integer

Nombre de visages similaires supérieurs retournés. La plage valide est [1, 1000]. La valeur par défaut est 20.
mode

FindSimilarMatchMode

Mode de recherche de visage similaire. Il peut s’agir de « matchPerson » ou de « matchFace ». La valeur par défaut est « matchPerson ».

Réponses

Nom Type Description
200 OK

FindSimilarResult[]

Un appel réussi retourne un tableau des visages les plus similaires représentés dans faceId si le paramètre d’entrée est faceIds ou persistedFaceId si le paramètre d’entrée est faceListId ou largeFaceListId.
Other Status Codes

FaceErrorResponse

Réponse d’erreur inattendue.

En-têtes

x-ms-error-code: string

Sécurité

Ocp-Apim-Subscription-Key

Clé secrète de votre abonnement Azure AI Face.

Type: apiKey
Dans: header

AADToken

Flux OAuth2 Azure Active Directory

Type: oauth2
Flux: accessCode
URL d’autorisation: https://api.example.com/oauth2/authorize
URL du jeton: https://api.example.com/oauth2/token

Étendues

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

Exemples

Find Similar among Face IDs

Exemple de requête

POST {endpoint}/face/v1.2-preview.1/findsimilars

{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "maxNumOfCandidatesReturned": 3,
  "mode": "matchPerson",
  "faceIds": [
    "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
    "be386ab3-af91-4104-9e6d-4dae4c9fddb7"
  ]
}

Exemple de réponse

Code d’état:
200 
[
  {
    "confidence": 0.9,
    "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9"
  }
]

Définitions

Nom Description
FaceError

Objet d’erreur. Pour plus d’informations sur les codes d’erreur et les messages retournés par le service Visage, reportez-vous au lien suivant : https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse

Réponse contenant les détails de l’erreur.
FindSimilarResult

Corps de la réponse pour rechercher une opération de visage similaire.

FaceError

Objet d’erreur. Pour plus d’informations sur les codes d’erreur et les messages retournés par le service Visage, reportez-vous au lien suivant : https://aka.ms/face-error-codes-and-messages.

Nom Type Description
code

string

Un ensemble de codes d’erreur définis par le serveur.
message

string

Représentation lisible par l’homme de l’erreur.

FaceErrorResponse

Réponse contenant les détails de l’erreur.

Nom Type Description
error

FaceError

Objet d’erreur.

FindSimilarResult

Corps de la réponse pour rechercher une opération de visage similaire.

Nom Type Description
confidence

number

Valeur de confiance du candidat. Plus la confiance est élevée, plus elle est similaire. Plage comprise entre [0,1].
faceId

string

faceId du visage candidat lorsqu’il est trouvé par faceIds. FaceId est créé par « Detect » et expire 24 heures après l’appel de détection.
persistedFaceId

string

persistedFaceId du visage candidat lors de la recherche par faceListId ou largeFaceListId. persistedFaceId dans la liste des visages/liste de visages volumineux est conservé et n’expirera pas.