Face Recognition Operations - Find Similar

Dienst:

Azure AI Services

API-Version:

v1.2-preview.1

Die faceId des Abfragegesichts wird durchsucht, um die ähnlich aussehenden Gesichter aus einem faceId-Array zu durchsuchen. Ein FaceId-Array enthält die von Detect erstellten Gesichter.
Je nach Eingabe enthält die zurückgegebene Liste ähnlicher Gesichter FaceIds oder persistedFaceIds, die nach Ähnlichkeit bewertet wurden.

Die Suche ähnelt zwei Arbeitsmodi: "matchPerson" und "matchFace". "matchPerson" ist der Standardmodus, in dem versucht wird, Gesichter derselben Person wie möglich mithilfe interner Schwellenwerte für dieselbe Person zu finden. Es ist nützlich, die anderen Fotos einer bekannten Person zu finden. Beachten Sie, dass eine leere Liste zurückgegeben wird, wenn keine Gesichter die internen Schwellenwerte überschreiten. Der Modus "matchFace" ignoriert Schwellenwerte für die gleiche Person und gibt trotzdem gleichrangige Gesichter zurück, auch wenn die Ähnlichkeit niedrig ist. Es kann in den Fällen verwendet werden, wie die Suche nach prominenten Gesichtern.

Das 'recognitionModel', das der Abfrage-FaceId zugeordnet ist, sollte mit dem vom Target FaceId-Array verwendeten 'recognitionModel' identisch sein.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
apiVersion	path	True	string	API-Version
endpoint	path	True	string uri	Unterstützte Cognitive Services-Endpunkte (Protokoll und Hostname, z. B. https://{resource-name}.cognitiveservices.azure.com).

Anforderungstext

Name	Erforderlich	Typ	Beschreibung
faceId	True	string	faceId des Abfragegesichts. Der Benutzer muss zuerst "Detect" aufrufen, um eine gültige FaceId zu erhalten. Beachten Sie, dass diese faceId nicht beibehalten wird und 24 Stunden nach dem Erkennungsaufruf abläuft.
faceIds	True	string[]	Ein Array von Kandidaten faceIds. Alle werden von "Erkennen" erstellt, und die FaceIds laufen 24 Stunden nach dem Erkennungsaufruf ab. Die Anzahl der faceIds ist auf 1000 beschränkt.
maxNumOfCandidatesReturned		integer	Die Anzahl der zurückgegebenen oberen ähnlichen Gesichter. Der gültige Bereich ist [1, 1000]. Der Standardwert ist 20.
mode		FindSimilarMatchMode	Ähnlicher Suchmodus für Die Gesichtssuche. Dies kann "matchPerson" oder "matchFace" sein. Der Standardwert ist "matchPerson".

Antworten

Name	Typ	Beschreibung
200 OK	FindSimilarResult[]	Ein erfolgreicher Aufruf gibt ein Array der ähnlichsten Gesichter zurück, die in faceId dargestellt werden, wenn der Eingabeparameter faceIds oder persistedFaceId ist, wenn der Eingabeparameter faceListId oder largeFaceListId ist.
Other Status Codes	FaceErrorResponse	Unerwartete Fehlerantwort. Header x-ms-error-code: string

Sicherheit

Ocp-Apim-Subscription-Key

Der geheime Schlüssel für Ihr Azure AI Face-Abonnement.

Typ: apiKey
In: header

AADToken

Der Azure Active Directory OAuth2-Fluss

Typ: oauth2
Ablauf: accessCode
Autorisierungs-URL: https://api.example.com/oauth2/authorize
Token-URL: https://api.example.com/oauth2/token

Bereiche

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

Beispiele

Find Similar among Face IDs

Beispielanforderung

HTTP

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"
  ]
}

Beispiel für eine Antwort

Statuscode:

200

[
  {
    "confidence": 0.9,
    "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9"
  }
]

Definitionen

Name	Beschreibung
FaceError	Das Fehlerobjekt. Ausführliche Informationen zu Fehlercodes und Nachrichten, die vom Face Service zurückgegeben werden, finden Sie unter folgendem Link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Eine Antwort, die Fehlerdetails enthält.
FindSimilarResult	Antworttext für die Suche nach ähnlichen Gesichtsvorgängen.

FaceError

Das Fehlerobjekt. Ausführliche Informationen zu Fehlercodes und Nachrichten, die vom Face Service zurückgegeben werden, finden Sie unter folgendem Link: https://aka.ms/face-error-codes-and-messages.

Name	Typ	Beschreibung
code	string	Eine serverdefinierte Gruppe von Fehlercodes.
message	string	Eine lesbare Darstellung des Fehlers.

FaceErrorResponse

Eine Antwort, die Fehlerdetails enthält.

Name	Typ	Beschreibung
error	FaceError	Das Fehlerobjekt.

FindSimilarResult

Antworttext für die Suche nach ähnlichen Gesichtsvorgängen.

Name	Typ	Beschreibung
confidence	number	Konfidenzwert des Kandidaten. Je höher das Vertrauen ist, desto ähnlicher. Bereich zwischen [0,1].
faceId	string	faceId des Kandidatengesichts, wenn nach faceIds gesucht wird. faceId wird von "Detect" erstellt und läuft 24 Stunden nach dem Erkennungsaufruf ab.
persistedFaceId	string	persistedFaceId of candidate face when find by faceListId or largeFaceListId. persistedFaceId in face list/large face list is persisted and will not expire.