Person Group Operations - Add Person Group Person Face

Service:

Azure AI Services

API Version:

v1.1-preview.1

Hinzufügen eines Gesichts zu einer Person zu einer Personengruppe zur Gesichtserkennung oder Überprüfung.
Um ein Bild zu behandeln, das mehrere Gesichter enthält, kann die Eingabefläche als Bild mit einem TargetFace-Rechteck angegeben werden. Es wird eine persistedFaceId zurückgegeben, die das hinzugefügte Gesicht darstellt. Es wird kein Bild gespeichert. Nur die extrahierten Gesichtserkennungsfeatures werden auf dem Server gespeichert, bis "Person Group Person Face löschen", "Person Group Person Person löschen" oder "Personengruppe löschen" aufgerufen wird.

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

• • Eine höhere Qualität der Gesichtsbilder bedeutet eine bessere Erkennungsgenauigkeit. Bitte berücksichtigen Sie hochwertige Gesichter: Frontal, Klar und Gesichtsgröße beträgt 200 x 200 Pixel (100 Pixel zwischen den 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 liegt zwischen 1 KB und 6 MB.
  • Das Rechteck "targetFace" sollte ein Gesicht enthalten. Null oder mehrere Gesichter werden als Fehler betrachtet. Wenn das bereitgestellte "targetFace"-Rechteck nicht von "Detect" zurückgegeben wird, gibt es keine Garantie, dass das Gesicht erfolgreich erkannt und hinzugefügt wird.
  • Außerhalb der erkennbaren Gesichtsgröße (36 x 36 bis 4096 x 4096 Pixel), große Kopfhaltung oder große Okklusionen führen zu Fehlern.
  • 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 einer Größe von mehr als 1920 x 1080 Pixel benötigen eine proportional größere Mindestgröße.
  • Es können verschiedene "detectionModel"-Werte angegeben 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

POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces

With optional parameters:

POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces?_overload=addPersonGroupPersonFace&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).
personGroupId	path	True	string	ID des Containers. Regex pattern: ^[a-z0-9-_]+$
personId	path	True	string uuid	ID der Person.
detectionModel	query		DetectionModel	Das "detectionModel", das den erkannten FaceIds zugeordnet ist. Unterstützte "detectionModel"-Werte sind "detection_01", "detection_02" und "detection_03". Der Standardwert ist "detection_01".
targetFace	query		integer[]	Ein Gesichtsrechteck zum Angeben des Zielgesichts, 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 1.000.

Anforderungstext

Media Types: "application/octet-stream"

Name	Typ	Beschreibung
imageContent	string	Das zu analysierende Bild

Antworten

Name	Typ	Beschreibung
200 OK	AddFaceResult	Ein erfolgreicher Aufruf gibt eine neue persistedFaceId zurück.
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 KI-Gesichtserkennungsabonnement.

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

Add Face to PersonGroup Person

Sample Request

HTTP

POST {endpoint}/face/v1.1-preview.1/persongroups/your_person_group_id/persons/25985303-c537-4467-b41d-bdb45cd95ca1/persistedfaces?_overload=addPersonGroupPersonFace&targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

"<your-image-bytes-here>"

Sample Response

Status code:

200

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

Definitionen

Name	Beschreibung
AddFaceResult	Antworttext zum Hinzufügen von Gesichtern.
DetectionModel	Das "detectionModel", das den erkannten FaceIds zugeordnet ist. Unterstützte "detectionModel"-Werte sind "detection_01", "detection_02" und "detection_03". Der Standardwert ist "detection_01".
FaceError	Das Fehlerobjekt. Ausführliche Informationen zu Fehlercodes und Meldungen, 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.

AddFaceResult

Antworttext zum Hinzufügen von Gesichtern.

Name	Typ	Beschreibung
persistedFaceId	string	Beibehaltene Gesichtserkennungs-ID des hinzugefügten Gesichts, die beibehalten wird und nicht abläuft. Anders als faceId, die in "Detect" erstellt wird und 24 Stunden nach dem Erkennungsaufruf abläuft.

DetectionModel

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

Name	Typ	Beschreibung
detection_01	string	Das Standarderkennungsmodell. Empfohlen für die Naherkennung des Frontalgesichts. In Szenarien mit außergewöhnlich großem Winkel (Kopfhaltung), verdeckten Gesichtern oder falscher Bildausrichtung werden die Gesichter in solchen Fällen möglicherweise nicht erkannt.
detection_02	string	Erkennungsmodell im Mai 2019 mit verbesserter Genauigkeit, insbesondere auf kleinen, seiten- und verschwommenen Gesichtern.
detection_03	string	Das im Februar 2021 veröffentlichte Erkennungsmodell mit verbesserter Genauigkeit, insbesondere bei kleinen Gesichtern.

FaceError

Das Fehlerobjekt. Ausführliche Informationen zu Fehlercodes und Meldungen, 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 von einem serverdefiniertem Satz von Fehlercodes.
message	string	Eine lesbare Darstellung des Fehlers.

FaceErrorResponse

Eine Antwort, die Fehlerdetails enthält.

Name	Typ	Beschreibung
error	FaceError	Das Fehlerobjekt.