Freigeben über

Face Recognition Operations - Find Similar From Face List

  • Referenz
Dienst:
Azure AI Services
API-Version:
v1.2-preview.1

Die FaceId der Abfrageseite, um die ähnlich aussehenden Gesichter aus einer Gesichtsliste zu durchsuchen. Eine "faceListId" wird von "Face List erstellen" erstellt.
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 von der Ziel-Gesichtsliste 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.
faceListId True

string

Eine vorhandene vom Benutzer angegebene eindeutige Kandidaten-Gesichtsliste, die in "Face List erstellen" erstellt wurde. Die Gesichtsliste enthält eine Gruppe 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 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 from FaceList

Beispielanforderung

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

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

Beispiel für eine Antwort

Statuscode:
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 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.