Freigeben über


Person Group Operations - Add Person Group Person Face

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
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-Muster: ^[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.

Header

x-ms-error-code: string

Sicherheit

Ocp-Apim-Subscription-Key

Der geheime Schlüssel für Ihr Azure KI-Gesichtserkennungsabonnement.

Typ: apiKey
In: header

AADToken

Der Azure Active Directory OAuth2-Flow

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 PersonGroup Person

Beispielanforderung

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>"

Beispiel für eine Antwort

{
  "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.