Face Recognition Operations - Find Similar

  • Referenz
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

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.