Person Group Operations - Add Person Group Person Face

Usługa:

Azure AI Services

Wersja interfejsu API:

v1.2-preview.1

Dodaj twarz do osoby do grupy osób w celu identyfikacji twarzy lub weryfikacji.
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ń osobę z grupy osób", "Usuń osobę grupę osób" lub "Usuń grupę osób".

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

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

Z parametrami opcjonalnymi:

POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces?_overload=addPersonGroupPersonFace&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).
personGroupId	path	True	string	Identyfikator kontenera. Wzorzec wyrażenia regularnego: ^[a-z0-9-_]+$
personId	path	True	string uuid	Identyfikator osoby.
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
200 OK	AddFaceResult	Pomyślne wywołanie zwraca nowy utrwaloneFaceId.
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 PersonGroup Person

Przykładowe żądanie

HTTP

POST {endpoint}/face/v1.2-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>"

Przykładowa odpowiedź

Kod stanu:

200

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

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.