Person Directory Operations - Add Person Face

Usługa:

Azure AI Services

Wersja interfejsu API:

v1.2-preview.1

Dodaj twarz do osoby (zobacz Katalog osób "Utwórz osobę") na potrzeby identyfikacji lub weryfikacji twarzy.
Aby poradzić sobie z obrazem zawierającym wiele twarzy, można określić twarz wejściową jako obraz z prostokątem targetFace. Zwraca on utrwalonego identyfikatoraFaceId reprezentującego dodaną twarz. Nie będzie przechowywany żaden obraz. Tylko wyodrębnione funkcje twarzy będą przechowywane na serwerze, dopóki nie zostanie wywołana funkcja "Usuń twarz osoby" lub "Usuń osobę".

Należy pamiętać, że utrwalone identyfikatoryFaceId różnią się od identyfikatora faceId wygenerowanego przez element "Detect".

• • Wyższa jakość obrazu twarzy oznacza lepszą precyzję rozpoznawania. Należy wziąć pod uwagę wysokiej jakości twarze: przednie, jasne i rozmiar twarzy to 200x200 pikseli (100 pikseli między oczami) lub większy.
  • Każdy wpis osoby może pomieścić do 248 twarzy.
  • Obsługiwane są formaty JPEG, PNG, GIF (pierwsza ramka) i BMP. Dozwolony rozmiar pliku obrazu wynosi od 1 KB do 6 MB.
  • Prostokąt "targetFace" powinien zawierać jedną twarz. Zero lub wiele twarzy zostanie uznanych za błąd. Jeśli podany prostokąt "targetFace" nie jest zwracany z "Detect", nie ma gwarancji, że można wykryć i dodać twarz pomyślnie.
  • Poza wykrywalnym rozmiarem twarzy (36x36 - 4096x4096 pikseli), dużą pozę głowy lub dużymi okluzjami spowoduje błędy.
  • Minimalny rozmiar twarzy wykrywalnej to 36x36 pikseli na obrazie nie większym niż 1920 x 1080 pikseli. Obrazy o wymiarach wyższych niż 1920 x 1080 pikseli będą potrzebować proporcjonalnie większego minimalnego rozmiaru twarzy.
  • Można podać różne wartości "detectionModel". Aby użyć i porównać różne modele wykrywania, zapoznaj się z https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
• • Dodawanie/usuwanie twarzy do/z tej samej osoby zostanie przetworzone sekwencyjnie. Równoległe przetwarzanie dodawania/usuwania twarzy do/z różnych osób.
  • Jest to długotrwała operacja. Użyj nagłówka odpowiedzi "Operation-Location", aby określić, kiedy operacja AddFace została pomyślnie rozpropagowana dla przyszłych żądań do "Zidentyfikuj". Aby uzyskać więcej informacji na temat Operation-Locations zobacz "Pobieranie stanu operacji rozpoznawania twarzy".

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

Z parametrami opcjonalnymi:

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

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
apiVersion	path	True	string	Wersja interfejsu API
endpoint	path	True	string uri	Obsługiwane punkty końcowe usług Cognitive Services (protokół i nazwa hosta, na przykład: https://{nazwa-zasobu}.cognitiveservices.azure.com).
personId	path	True	string uuid	Identyfikator osoby.
recognitionModel	path	True	RecognitionModel	Element "recognitionModel" skojarzony z twarzami.
detectionModel	query		DetectionModel	Element "detectionModel" skojarzony z wykrytymi identyfikatorami faceId. Obsługiwane wartości "detectionModel" obejmują wartości "detection_01", "detection_02" i "detection_03". Wartość domyślna to "detection_01".
targetFace	query		integer[]	Prostokąt twarzy określający docelową twarz do dodania do osoby w formacie "targetFace=left", top,width,height".
userData	query		string	Dane dostarczone przez użytkownika dołączone do twarzy. Limit rozmiaru to 1K.

Treść żądania

Media Types: "application/octet-stream"

Nazwa	Typ	Opis
imageContent	string	Obraz do przeanalizowania

Odpowiedzi

Nazwa	Typ	Opis
202 Accepted	AddFaceResult	Pomyślne wywołanie zwraca pustą treść odpowiedzi. Usługa zaakceptowała żądanie i wkrótce rozpocznie przetwarzanie. Klient może wysyłać zapytania dotyczące stanu operacji i wyniku przy użyciu adresu URL określonego w nagłówku odpowiedzi "Operation-Location". Adres URL wygasa w ciągu 48 godzin. Nagłówki Location: string operation-Location: string
Other Status Codes	FaceErrorResponse	Nieoczekiwana odpowiedź na błąd. Nagłówki x-ms-error-code: string

Zabezpieczenia

Ocp-Apim-Subscription-Key

Klucz tajny subskrypcji rozpoznawania twarzy w usłudze Azure AI.

Typ: apiKey
W: header

AADToken

Przepływ OAuth2 usługi Azure Active Directory

Typ: oauth2
Flow: accessCode
Adres URL autoryzacji: https://api.example.com/oauth2/authorize
Adres URL tokenu: https://api.example.com/oauth2/token

Zakresy

Nazwa	Opis
https://cognitiveservices.azure.com/.default

Przykłady

Add Face to a PersonDirectory Person

Przykładowe żądanie

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

Przykładowa odpowiedź

Kod stanu:

202

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

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

Definicje

Nazwa	Opis
AddFaceResult	Treść odpowiedzi na potrzeby dodawania twarzy.
DetectionModel	Element "detectionModel" skojarzony z wykrytymi identyfikatorami faceId. Obsługiwane wartości "detectionModel" obejmują wartości "detection_01", "detection_02" i "detection_03". Wartość domyślna to "detection_01".
FaceError	Obiekt błędu. Aby uzyskać szczegółowe informacje na temat kodów błędów i komunikatów zwracanych przez usługę rozpoznawania twarzy, zapoznaj się z następującym linkiem: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Odpowiedź zawierająca szczegóły błędu.
RecognitionModel	Model rozpoznawania twarzy.

AddFaceResult

Treść odpowiedzi na potrzeby dodawania twarzy.

Nazwa	Typ	Opis
persistedFaceId	string	Utrwalone face ID dodanej twarzy, która jest utrwalone i nie wygaśnie. Inaczej niż faceId, który jest tworzony w funkcji "Wykryj" i wygaśnie w ciągu 24 godzin po wywołaniu wykrywania.

DetectionModel

Element "detectionModel" skojarzony z wykrytymi identyfikatorami faceId. Obsługiwane wartości "detectionModel" obejmują wartości "detection_01", "detection_02" i "detection_03". Wartość domyślna to "detection_01".

Nazwa	Typ	Opis
detection_01	string	Domyślny model wykrywania. Zaleca się wykrywanie twarzy niemal przedniej. W przypadku scenariuszy z wyjątkowo dużym kątem (pozy głowy) twarze, okludowane twarze lub niewłaściwa orientacja obrazu, twarze w takich przypadkach mogą nie zostać wykryte.
detection_02	string	Model wykrywania wydany w maju 2019 r. z lepszą dokładnością szczególnie na małych, bocznych i rozmytych twarzach.
detection_03	string	Model wykrywania wydany w 2021 r. w lutym 2021 r. z lepszą dokładnością szczególnie na małych twarzach.

FaceError

Obiekt błędu. Aby uzyskać szczegółowe informacje na temat kodów błędów i komunikatów zwracanych przez usługę rozpoznawania twarzy, zapoznaj się z następującym linkiem: https://aka.ms/face-error-codes-and-messages.

Nazwa	Typ	Opis
code	string	Jeden z zdefiniowanych przez serwer zestaw kodów błędów.
message	string	Czytelna dla człowieka reprezentacja błędu.

FaceErrorResponse

Odpowiedź zawierająca szczegóły błędu.

Nazwa	Typ	Opis
error	FaceError	Obiekt błędu.

RecognitionModel

Model rozpoznawania twarzy.

Nazwa	Typ	Opis
recognition_01	string	Domyślny model rozpoznawania dla "Detect". Wszystkie te identyfikatory faceId utworzone przed marcem 2019 r. są związane z tym modelem rozpoznawania.
recognition_02	string	Model rozpoznawania wydany w marcu 2019 r.
recognition_03	string	Model rozpoznawania wydany w maju 2020 r.
recognition_04	string	Model rozpoznawania wydany w lutym 2021 r. Zaleca się użycie tego modelu rozpoznawania w celu uzyskania lepszej dokładności rozpoznawania.