Person Directory Operations - Add Person Face

Service:

Azure AI Services

API-versie:

v1.2-preview.1

Voeg een gezicht toe aan een persoon (zie Person Directory 'Create Person') voor gezichtsidentificatie of verificatie.
Als u een afbeelding met meerdere gezichten wilt verwerken, kan het invoervlak worden opgegeven als een afbeelding met een targetFace-rechthoek. Het retourneert een persistenteFaceId die het toegevoegde gezicht vertegenwoordigt. Er wordt geen installatiekopieën opgeslagen. Alleen de geëxtraheerde gezichtsfuncties worden opgeslagen op de server totdat persoonsmap 'Persoonlijk gezicht verwijderen' of 'Persoon verwijderen' wordt aangeroepen.

Houd er rekening mee dat persistentFaceId verschilt van faceId die wordt gegenereerd door 'Detect'.

• • Hogere afbeeldingskwaliteit van gezicht betekent betere herkenningsprecisie. Overweeg gezichten van hoge kwaliteit: frontaal, helder en gezichtsgrootte is 200x200 pixels (100 pixels tussen ogen) of groter.
  • Elke persoon kan maximaal 248 gezichten bevatten.
  • JPEG-, PNG-, GIF-, GIF-indeling (het eerste frame) en BMP-indeling worden ondersteund. De toegestane grootte van het afbeeldingsbestand is van 1 KB tot 6 MB.
  • De rechthoek targetFace moet één gezicht bevatten. Nul of meerdere gezichten worden beschouwd als een fout. Als de opgegeven 'targetFace'-rechthoek niet wordt geretourneerd door 'Detecteren', is er geen garantie om het gezicht te detecteren en toe te voegen.
  • Uit detecteerbare gezichtsgrootte (36x36 - 4096x4096 pixels), grote hoofdhouding of grote occlusies leiden tot storingen.
  • De minimale detecteerbare gezichtsgrootte is 36x36 pixels in een afbeelding die niet groter is dan 1920x1080 pixels. Afbeeldingen met afmetingen die hoger zijn dan 1920x1080 pixels hebben een proportioneel grotere minimale gezichtsgrootte nodig.
  • Er kunnen verschillende 'detectionModel'-waarden worden opgegeven. Als u verschillende detectiemodellen wilt gebruiken en vergelijken, raadpleegt u https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
• • Het toevoegen/verwijderen van gezichten aan/van dezelfde persoon wordt opeenvolgend verwerkt. Het toevoegen/verwijderen van gezichten aan/van verschillende personen wordt parallel verwerkt.
  • Dit is een langdurige bewerking. Gebruik antwoordheader 'Operation-Location' om te bepalen wanneer de AddFace-bewerking is doorgegeven voor toekomstige aanvragen om te identificeren. Zie 'Gezichtsbewerkingsstatus ophalen' voor meer informatie over Operation-Locations.

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

Met optionele parameters:

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

URI-parameters

Name	In	Vereist	Type	Description
apiVersion	path	True	string	API-versie
endpoint	path	True	string uri	Ondersteunde Cognitive Services-eindpunten (protocol en hostnaam, bijvoorbeeld: https://{resource-name}.cognitiveservices.azure.com).
personId	path	True	string uuid	Persoons-id van de persoon.
recognitionModel	path	True	RecognitionModel	Het 'recognitionModel' dat is gekoppeld aan gezichten.
detectionModel	query		DetectionModel	Het 'detectionModel' dat is gekoppeld aan de gedetecteerde faceIds. Ondersteunde 'detectionModel'-waarden zijn 'detection_01', 'detection_02' en 'detection_03'. De standaardwaarde is 'detection_01'.
targetFace	query		integer[]	Een gezichtsrechthoek om het doelvlak op te geven dat aan een persoon moet worden toegevoegd, in de notatie targetFace=left,top,width,height.
userData	query		string	Door de gebruiker verstrekte gegevens die aan het gezicht zijn gekoppeld. De groottelimiet is 1K.

Aanvraagbody

Media Types: "application/octet-stream"

Name	Type	Description
imageContent	string	De afbeelding die moet worden geanalyseerd

Antwoorden

Name	Type	Description
202 Accepted	AddFaceResult	Een geslaagde aanroep retourneert een lege antwoordtekst. De service heeft de aanvraag geaccepteerd en wordt binnenkort verwerkt. De client kan een query uitvoeren op de bewerkingsstatus en het resultaat met behulp van de URL die is opgegeven in de antwoordheader Operation-Location. De URL verloopt over 48 uur. Kopteksten Location: string operation-Location: string
Other Status Codes	FaceErrorResponse	Een onverwachte foutreactie. Kopteksten x-ms-error-code: string

Beveiliging

Ocp-Apim-Subscription-Key

De geheime sleutel voor uw Azure AI Face-abonnement.

Type: apiKey
In: header

AADToken

De Azure Active Directory OAuth2-stroom

Type: oauth2
Stroom: accessCode
Autorisatie-URL: https://api.example.com/oauth2/authorize
Token-URL: https://api.example.com/oauth2/token

Bereiken

Name	Description
https://cognitiveservices.azure.com/.default

Voorbeelden

Add Face to a PersonDirectory Person

Voorbeeldaanvraag

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

Voorbeeldrespons

Statuscode:

202

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

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

Definities

Name	Description
AddFaceResult	Antwoordtekst voor het toevoegen van gezicht.
DetectionModel	Het 'detectionModel' dat is gekoppeld aan de gedetecteerde faceIds. Ondersteunde 'detectionModel'-waarden zijn 'detection_01', 'detection_02' en 'detection_03'. De standaardwaarde is 'detection_01'.
FaceError	Het foutobject. Raadpleeg de volgende koppeling voor uitgebreide informatie over foutcodes en berichten die worden geretourneerd door de Face-service: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Een antwoord met foutdetails.
RecognitionModel	Het herkenningsmodel voor het gezicht.

AddFaceResult

Antwoordtekst voor het toevoegen van gezicht.

Name	Type	Description
persistedFaceId	string	Permanente Face ID van het toegevoegde gezicht, dat behouden blijft en niet verloopt. Verschilt van faceId die wordt gemaakt in 'Detecteren' en verloopt binnen 24 uur na de detectieaanroep.

DetectionModel

Het 'detectionModel' dat is gekoppeld aan de gedetecteerde faceIds. Ondersteunde 'detectionModel'-waarden zijn 'detection_01', 'detection_02' en 'detection_03'. De standaardwaarde is 'detection_01'.

Name	Type	Description
detection_01	string	Het standaarddetectiemodel. Aanbevolen voor gezichtsdetectie in de buurt van frontale gezichten. Voor scenario's met uitzonderlijk grote hoek (hoofdhouding) gezichten, occluded gezichten of verkeerde afdrukstand, kunnen de gezichten in dergelijke gevallen niet worden gedetecteerd.
detection_02	string	Detectiemodel uitgebracht in 2019 met verbeterde nauwkeurigheid, met name op kleine, zij- en wazige gezichten.
detection_03	string	Detectiemodel uitgebracht in 2021 februari met verbeterde nauwkeurigheid, met name op kleine gezichten.

FaceError

Het foutobject. Raadpleeg de volgende koppeling voor uitgebreide informatie over foutcodes en berichten die worden geretourneerd door de Face-service: https://aka.ms/face-error-codes-and-messages.

Name	Type	Description
code	string	Een van een door de server gedefinieerde set foutcodes.
message	string	Een leesbare weergave van de fout.

FaceErrorResponse

Een antwoord met foutdetails.

Name	Type	Description
error	FaceError	Het foutobject.

RecognitionModel

Het herkenningsmodel voor het gezicht.

Name	Type	Description
recognition_01	string	Het standaardherkenningsmodel voor 'Detecteren'. Al deze faceIds die vóór 2019 maart zijn gemaakt, worden gekoppeld aan dit herkenningsmodel.
recognition_02	string	Het herkenningsmodel is uitgebracht in maart 2019.
recognition_03	string	Het herkenningsmodel is uitgebracht in 2020.
recognition_04	string	Het herkenningsmodel is uitgebracht in 2021 februari. Het is raadzaam om dit herkenningsmodel te gebruiken voor betere nauwkeurigheid van herkenning.