Face Recognition Operations - Find Similar

Service:

Azure AI Services

Version d'API:

v1.1-preview.1

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

Rechercher similaire a deux modes de travail, « matchPerson » et « matchFace ». « matchPerson » est le mode par défaut auquel il tente de trouver les visages de la même personne autant 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 sera retournée si aucune face ne dépasse les seuils internes. Le mode « matchFace » ignore les seuils de même personne et retourne de toute façon des visages classés similaires, 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 d'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 de la face de la requête. L’utilisateur doit d’abord appeler « Détecter » pour obtenir un faceId valide. Notez que ce faceId n’est pas persistant et expirera 24 heures après l’appel de détection.
faceIds	True	string[]	Tableau de faceIds candidats. Tous sont créés par « Détecter » et les faceIds expirent 24 heures après l’appel de détection. Le nombre de faceIds est limité à 1000.
maxNumOfCandidatesReturned		integer	Nombre de visages similaires les plus hauts 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 « 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

HTTP

POST {endpoint}/face/v1.1-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 des 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 semblable. Plage comprise entre [0,1].
faceId	string	faceId du visage candidat lors de la recherche par faceIds. faceId est créé par « Détecter » et expirera 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 de visages/grande liste de visages est conservé et n’expirera pas.