Face Recognition Operations - Find Similar From Large Face List

Service:

Azure AI Services

API Version:

v1.1-preview.1

Wenn Sie die faceId des Abfragegesichts angeben, um die ähnlich aussehenden Gesichter aus einer großen Gesichtsliste zu durchsuchen. Eine "largeFaceListId" wird von Create Große Gesichtsliste erstellt.
Abhängig von der Eingabe enthält die zurückgegebene Liste ähnlicher Gesichter faceIds oder persistedFaceIds, die nach Ähnlichkeit sortiert sind.

Find similar hat zwei Arbeitsmodi, "matchPerson" und "matchFace". "matchPerson" ist der Standardmodus, in dem versucht wird, Gesichter derselben Person so wie möglich zu finden, indem interne Schwellenwerte für dieselbe Person verwendet werden. Es ist nützlich, andere Fotos einer bekannten Person zu finden. Beachten Sie, dass eine leere Liste zurückgegeben wird, wenn keine Gesichter die internen Schwellenwerte überschreiten. Der "matchFace"-Modus ignoriert Schwellenwerte für dieselbe Person und gibt trotzdem ähnliche Gesichter zurück, auch wenn die Ähnlichkeit gering ist. Es kann in den Fällen verwendet werden, wie z. B. die Suche nach prominenten Gesichtern.

Das "recognitionModel", das der Abfrage-FaceId zugeordnet ist, sollte mit dem "recognitionModel" identisch sein, das von der Großen Gesichtsliste des Ziels verwendet wird.

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.
largeFaceListId	True	string	Eine vorhandene, vom Benutzer angegebene eindeutige Große Gesichtsliste, die in "Create Große Gesichtsliste" erstellt wurde. Große Gesichtserkennungsliste enthält eine Reihe von persistedFaceIds, die beibehalten werden und nie ablaufen.
maxNumOfCandidatesReturned		integer	Die Anzahl der zurückgegebenen oberen ähnlichen Gesichter. Der gültige Bereich ist [1, 1000]. Der Standardwert ist 20.
mode		FindSimilarMatchMode	Ähnlicher Gesichtssuchemodus. Es kann "matchPerson" oder "matchFace" sein. Der Standardwert ist "matchPerson".

Antworten

Name	Typ	Beschreibung
200 OK	FindSimilarResult[]	Bei einem erfolgreichen Aufruf wird ein Array mit den ähnlichsten Gesichtern zurückgegeben, die in faceId dargestellt werden, wenn der Eingabeparameter faceIds oder persistedFaceId ist, wenn der Eingabeparameter faceListId oder largeFaceListId ist.
Other Status Codes	FaceErrorResponse	Eine unerwartete Fehlerantwort. Headers x-ms-error-code: string

Sicherheit

Ocp-Apim-Subscription-Key

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

Type: apiKey
In: header

AADToken

Der Azure Active Directory OAuth2-Flow

Type: oauth2
Flow: accessCode
Authorization URL: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Scopes

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

Beispiele

Find Similar from LargeFaceList

Sample Request

HTTP

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

{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "maxNumOfCandidatesReturned": 3,
  "mode": "matchPerson",
  "largeFaceListId": "your_large_face_list_id"
}

Sample Response

Status code:

200

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

Definitionen

Name	Beschreibung
FaceError	Das Fehlerobjekt. Ausführliche Informationen zu Fehlercodes und Nachrichten, die vom Gesichtserkennungsdienst 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 Gesichtsoperationen.

FaceError

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

Name	Typ	Beschreibung
code	string	Einer der vom Server definierten Fehlercodes.
message	string	Eine für Menschen 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 Gesichtsoperationen.

Name	Typ	Beschreibung
confidence	number	Vertrauenswert des Kandidaten. Je höher die Zuverlässigkeit, desto ähnlicher. Bereich zwischen [0,1].
faceId	string	faceId des Kandidatengesichts, wenn von faceIds gefunden wird. faceId wird von "Detect" erstellt und läuft 24 Stunden nach dem Erkennungsaufruf ab.
persistedFaceId	string	persistedFaceId des Kandidatengesichts, wenn es durch faceListId oder largeFaceListId gefunden wird. persistedFaceId in Gesichtsliste/große Gesichtsliste wird beibehalten und läuft nicht ab.