Person Directory Operations - Add Person Face

Dienst:

Azure AI Services

API-Version:

v1.2-preview.1

Fügen Sie einer Person ein Gesicht hinzu (siehe Personenverzeichnis "Person erstellen") zur Gesichtsidentifikation oder Überprüfung.
Um mit einem Bild zu umgehen, das mehrere Gesichter enthält, kann die Eingabeoberfläche als Bild mit einem TargetFace-Rechteck angegeben werden. Es gibt eine persistedFaceId zurück, die das hinzugefügte Gesicht darstellt. Es wird kein Bild gespeichert. Nur die extrahierten Gesichtsfeatures werden auf dem Server gespeichert, bis "Person löschen" oder "Person löschen" aufgerufen wird.

Beachten Sie, dass persistedFaceId sich von "faceId" unterscheidet, die von "Detect" generiert wird.

• • Höhere Gesichtsbildqualität bedeutet eine bessere Erkennungsgenauigkeit. Berücksichtigen Sie qualitativ hochwertige Gesichter: Frontal-, Klar- und Gesichtsgröße beträgt 200 x 200 Pixel (100 Pixel zwischen Augen) oder größer.
  • Jeder Personeneintrag kann bis zu 248 Gesichter enthalten.
  • JPEG, PNG, GIF (der erste Frame) und BMP-Format werden unterstützt. Die zulässige Bilddateigröße beträgt 1 KB bis 6 MB.
  • Das Rechteck "targetFace" sollte ein Gesicht enthalten. Null oder mehrere Gesichter werden als Fehler betrachtet. Wenn das bereitgestellte Rechteck "targetFace" nicht von "Erkennen" zurückgegeben wird, gibt es keine Garantie, das Gesicht erfolgreich zu erkennen und hinzuzufügen.
  • Außerhalb der erkennbaren Gesichtsgröße (36 x 36 - 4096x4096 Pixel), große Kopfvorstellung oder große Okklusionen verursachen Fehler.
  • Die minimale erkennbare Gesichtsgröße beträgt 36 x 36 Pixel in einem Bild, das nicht größer als 1920 x 1080 Pixel ist. Bilder mit Abmessungen, die größer als 1920 x 1080 Pixel sind, benötigen eine proportional größere Mindestgröße.
  • Es können verschiedene "detectionModel"-Werte bereitgestellt werden. Informationen zum Verwenden und Vergleichen verschiedener Erkennungsmodelle finden Sie unter https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
• • Das Hinzufügen/Löschen von Gesichtern zu/aus derselben Person wird sequenziell verarbeitet. Das Hinzufügen/Löschen von Gesichtern zu/aus verschiedenen Personen wird parallel verarbeitet.
  • Dies ist ein lang ausgeführter Vorgang. Verwenden Sie den Antwortheader "Operation-Location", um zu bestimmen, wann der AddFace-Vorgang erfolgreich für zukünftige Anforderungen an "Identifizieren" weitergegeben wurde. Weitere Informationen zu Operation-Locations finden Sie unter "Get Face Operation Status".

POST {endpoint}/face/{apiVersion}/persons/{personId}/recognitionModels/{recognitionModel}/persistedfaces

Mit optionalen Parametern:

POST {endpoint}/face/{apiVersion}/persons/{personId}/recognitionModels/{recognitionModel}/persistedfaces?targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

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).
personId	path	True	string uuid	Personen-ID der Person.
recognitionModel	path	True	RecognitionModel	Das mit Gesichtern verknüpfte "recognitionModel".
detectionModel	query		DetectionModel	Das "detectionModel", das den erkannten FaceIds zugeordnet ist. Unterstützte 'detectionModel'-Werte umfassen "detection_01", "detection_02" und "detection_03". Der Standardwert ist "detection_01".
targetFace	query		integer[]	Ein Gesichtsrechteck, um das Zielgesicht anzugeben, das einer Person hinzugefügt werden soll, im Format "targetFace=left,top,width,height".
userData	query		string	Vom Benutzer bereitgestellte Daten, die an das Gesicht angefügt sind. Die Größenbeschränkung beträgt 1K.

Anforderungstext

Media Types: "application/octet-stream"

Name	Typ	Beschreibung
imageContent	string	Das zu analysierende Bild

Antworten

Name	Typ	Beschreibung
202 Accepted	AddFaceResult	Ein erfolgreicher Aufruf gibt einen leeren Antworttext zurück. Der Dienst hat die Anforderung angenommen und wird in Kürze mit der Verarbeitung beginnen. Der Client kann den Vorgangsstatus und das Ergebnis mithilfe der im Antwortheader "Operation-Location" angegebenen URL abfragen. Die URL läuft in 48 Stunden ab. Header Location: string operation-Location: string
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

Add Face to a PersonDirectory Person

Beispielanforderung

HTTP

POST {endpoint}/face/v1.2-preview.1/persons/85c0c630-c9c9-40f8-8a4e-f9ae4f926ea5/recognitionModels/recognition_01/persistedfaces?targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

"<your-image-bytes-here>"

Beispiel für eine Antwort

Statuscode:

202

location: https://contoso.com/operationstatus
operation-Location: https://contoso.com/operationstatus

{
  "persistedFaceId": "43897a75-8d6f-42cf-885e-74832febb055"
}

Definitionen

Name	Beschreibung
AddFaceResult	Antworttext zum Hinzufügen von Gesicht.
DetectionModel	Das "detectionModel", das den erkannten FaceIds zugeordnet ist. Unterstützte 'detectionModel'-Werte umfassen "detection_01", "detection_02" und "detection_03". Der Standardwert ist "detection_01".
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.
RecognitionModel	Das Erkennungsmodell für das Gesicht.

AddFaceResult

Antworttext zum Hinzufügen von Gesicht.

Name	Typ	Beschreibung
persistedFaceId	string	Persisted Face ID of the added face, which is persisted and will not expire. Anders als faceId, die in "Erkennen" erstellt wird und in 24 Stunden nach dem Erkennungsaufruf abläuft.

DetectionModel

Das "detectionModel", das den erkannten FaceIds zugeordnet ist. Unterstützte 'detectionModel'-Werte umfassen "detection_01", "detection_02" und "detection_03". Der Standardwert ist "detection_01".

Name	Typ	Beschreibung
detection_01	string	Das Standarderkennungsmodell. Empfohlen für die Nah frontale Gesichtserkennung. Bei Szenarien mit außergewöhnlich großen Winkeln (Kopf-Pose), verdeckten Gesichtern oder falscher Bildausrichtung werden die Gesichter in solchen Fällen möglicherweise nicht erkannt.
detection_02	string	Das 2019 veröffentlichte Erkennungsmodell wurde im Mai 2019 mit verbesserter Genauigkeit insbesondere auf kleinen, seitlichen und verschwommenen Gesichtern veröffentlicht.
detection_03	string	Das Im Februar 2021 veröffentlichte Erkennungsmodell mit verbesserter Genauigkeit insbesondere auf kleinen Gesichtern.

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.

RecognitionModel

Das Erkennungsmodell für das Gesicht.

Name	Typ	Beschreibung
recognition_01	string	Das Standarderkennungsmodell für "Erkennen". Alle faceIds, die vor dem März 2019 erstellt wurden, sind mit diesem Erkennungsmodell verbunden.
recognition_02	string	Erkennungsmodell, das im März 2019 veröffentlicht wurde.
recognition_03	string	Erkennungsmodell, das im Mai 2020 veröffentlicht wurde.
recognition_04	string	Erkennungsmodell, das im Februar 2021 veröffentlicht wurde. Es wird empfohlen, dieses Erkennungsmodell für eine bessere Erkennungsgenauigkeit zu verwenden.