Liveness Session Operations - Create Liveness With Verify Session

Odwołanie

Usługa:: Azure AI Services

Wersja interfejsu API:: v1.2

Utwórz nową sesję liveness z weryfikacją. Podaj obraz weryfikacji podczas tworzenia sesji.
Sesja jest najlepsza w scenariuszach urządzeń klienckich, w których deweloperzy chcą autoryzować urządzenie klienckie tylko do wykrywania aktualności bez udzielania pełnego dostępu do swojego zasobu. Utworzone sesje mają ograniczony zakres życia i autoryzuje tylko klientów do wykonania żądanej akcji przed wygaśnięciem dostępu.

Uprawnienia obejmują...

- Możliwość wywołania /detectLivenessWithVerify/singleModal dla maksymalnie 3 ponownych prób.
- Okres istnienia tokenu to 10 minut.

Nuta

- Dostęp klienta można odwołać, usuwając sesję przy użyciu operacji Usuń żywotność za pomocą weryfikacji sesji.
- Aby pobrać wynik, użyj sesji Uzyskiwanie aktualności za pomocą weryfikacji.
- Aby przeprowadzić inspekcję poszczególnych żądań wysyłanych przez klienta do zasobu, użyj pozycji Lista aktywności z weryfikacją wpisów inspekcji sesji.

POST {endpoint}/face/{apiVersion}/detectLivenessWithVerify-sessions

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
livenessOperationMode	formData	True	LivenessOperationMode	Typ trybu liveness, który powinien być zgodny z klientem.
verifyImage	formData	True	file	Strumień obrazu do zweryfikowania. Pole nagłówka Content-Disposition dla tej części musi mieć nazwę pliku.
authTokenTimeToLiveInSeconds	formData		integer (int32) minimum: 60 maximum: 86400	Sekundy sesji powinny trwać. Zakres wynosi od 60 do 86400 sekund. Wartość domyślna to 600.
deviceCorrelationId	formData		string	Unikatowy identyfikator GUID dla każdego urządzenia użytkownika końcowego. Ma to zapewnić ograniczenie szybkości i anty-młotek. Jeśli parametr "deviceCorrelationIdSetInClient" ma wartość true w tym żądaniu, ten parametr "deviceCorrelationId" musi mieć wartość null.
deviceCorrelationIdSetInClient	formData		boolean	Czy zezwolić klientowi na ustawienie własnego identyfikatora "deviceCorrelationId" za pomocą zestawu SDK usługi Vision. Wartość domyślna to false, a wartość "deviceCorrelationId" musi być ustawiona w tej treści żądania.
enableSessionImage	formData		boolean	Bez względu na to, czy przechowujesz obraz sesji.
livenessModelVersion	formData		LivenessModel	Wersja modelu używana do klasyfikacji aktualności. Jest to opcjonalny parametr i jeśli nie zostanie określony, zostanie wybrana najnowsza obsługiwana wersja modelu
returnVerifyImageHash	formData		boolean	Określa, czy zwracany jest skrót obrazu weryfikacji.
verifyConfidenceThreshold	formData		number (float) minimum: 0 maximum: 1	Próg ufności weryfikacji twarzy. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją. https://learn.microsoft.com/legal/cognitive-services/face/characteristics-and-limitations?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#recognition-confidence-score
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).

Odpowiedzi

Nazwa	Typ	Opis
200 OK	LivenessWithVerifySession	Pomyślne wywołanie tworzy sesję dla urządzenia klienckiego i udostępnia token autoryzacji do użycia przez aplikację kliencką w ograniczonym celu i czasie.
Other Status Codes	FaceErrorResponse	Nieoczekiwana odpowiedź na błąd. Nagłówki x-ms-error-code: string

Nazwa

Typ

Opis

200 OK

LivenessWithVerifySession

Pomyślne wywołanie tworzy sesję dla urządzenia klienckiego i udostępnia token autoryzacji do użycia przez aplikację kliencką w ograniczonym celu i czasie.

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

Create LivenessWithVerify Session

Przykładowe żądanie

HTTP

POST {endpoint}/face/v1.2/detectLivenessWithVerify-sessions

Przykładowa odpowiedź

Kod stanu:: 200

{
  "sessionId": "b12e033e-bda7-4b83-a211-e721c661f30e",
  "authToken": "eyJhbGciOiJFUzI1NiIsIm",
  "status": "NotStarted",
  "modelVersion": "2024-11-15",
  "results": {
    "attempts": [],
    "verifyReferences": [
      {
        "referenceType": "image",
        "faceRectangle": {
          "top": 316,
          "left": 131,
          "width": 498,
          "height": 677
        },
        "qualityForRecognition": "high"
      }
    ]
  }
}

Definicje

Nazwa	Opis
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.
FaceRectangle	Prostokąt, w którym można znaleźć twarz.
ImageType	Typ obrazu.
LivenessColorDecisionTarget	Element docelowy z obrazu koloru używany do klasyfikacji aktualności.
LivenessDecision	Wynik klasyfikacji liveness.
LivenessDecisionTargets	Elementy docelowe używane do klasyfikacji dostępności.
LivenessError	Błąd klasyfikacji aktualności.
LivenessModel	Wersja modelu używana do klasyfikacji aktualności.
LivenessOperationMode	Tryb operacji liveness umożliwiający obsługę środowiska użytkownika końcowego klienta.
LivenessWithVerifyOutputs	Dane wyjściowe weryfikacji twarzy.
LivenessWithVerifyReference	Szczegóły twarzy na potrzeby weryfikacji.
LivenessWithVerifyResult	Wyniki liveness z weryfikacją wywołania.
LivenessWithVerifySession	Wynik sesji wykrywania aktualności przy użyciu weryfikacji.
LivenessWithVerifySessionAttempt	Żywość z próbą weryfikacji sesji.
LivenessWithVerifySessionResults	Wyniki liveness z weryfikacją sesji.
OperationState	Bieżący stan sesji.
QualityForRecognition	Wskazuje jakość obrazu do rozpoznawania.

FaceError

Objekt

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

Objekt

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

Nazwa	Typ	Opis
error	FaceError	Obiekt błędu.

FaceRectangle

Objekt

Prostokąt, w którym można znaleźć twarz.

Nazwa	Typ	Opis
height	integer (int32)	Wysokość prostokąta w pikselach.
left	integer (int32)	Odległość od lewej krawędzi, jeśli obraz do lewej krawędzi prostokąta w pikselach.
top	integer (int32)	Odległość od górnej krawędzi, jeśli obraz do górnej krawędzi prostokąta w pikselach.
width	integer (int32)	Szerokość prostokąta w pikselach.

ImageType

Wyliczanie

Typ obrazu.

Wartość	Opis
Color	Obraz kolorowy.
Depth	Obraz głębokości.
Infrared	Obraz podczerwieni.

LivenessColorDecisionTarget

Objekt

Element docelowy z obrazu koloru używany do klasyfikacji aktualności.

Nazwa	Typ	Opis
faceRectangle	FaceRectangle	Region twarzy, w którym dokonano klasyfikacji liveness.

LivenessDecision

Wyliczanie

Wynik klasyfikacji liveness.

Wartość	Opis
realface	Algorytm sklasyfikował docelową twarz jako rzeczywistą.
spoofface	Algorytm sklasyfikował docelową twarz jako fałsz.
uncertain	Algorytm nie może sklasyfikować twarzy docelowej jako rzeczywistej lub fałszowania.

LivenessDecisionTargets

Objekt

Elementy docelowe używane do klasyfikacji dostępności.

Nazwa	Typ	Opis
color	LivenessColorDecisionTarget	Element docelowy z obrazu koloru używany do klasyfikacji aktualności.

LivenessError

Objekt

Błąd klasyfikacji aktualności.

Nazwa	Typ	Opis
code	string	Kod błędu.
message	string	Komunikat o błędzie.
targets	LivenessDecisionTargets	Elementy docelowe używane do klasyfikacji dostępności.

LivenessModel

Wyliczanie

Wersja modelu używana do klasyfikacji aktualności.

Wartość	Opis
2024-11-15

LivenessOperationMode

Wyliczanie

Tryb operacji liveness umożliwiający obsługę środowiska użytkownika końcowego klienta.

Wartość	Opis
Passive	Wykorzystuje pasywną technikę utrzymania, która nie wymaga żadnych dodatkowych akcji od użytkownika. Wymaga normalnego oświetlenia wewnętrznego i wysokiej jasności ekranu w celu uzyskania optymalnej wydajności. W związku z tym ten tryb ma wąskią kopertę operacyjną i nie będzie odpowiedni dla scenariuszy, które wymagają, aby użytkownik końcowy był w jasnych warunkach oświetleniowych. Uwaga: jest to jedyny obsługiwany tryb rozwiązania Dla urządzeń przenośnych (iOS i Android).
PassiveActive	Ten tryb wykorzystuje hybrydową technikę pasywnej lub aktywnej aktywności, która wymaga współpracy użytkowników. Jest zoptymalizowany pod kątem wymagania aktywnego ruchu tylko w warunkach nieoptymalnych oświetlenia. W przeciwieństwie do trybu pasywnego ten tryb nie ma ograniczeń oświetlenia, a tym samym oferuje szerszą kopertę operacyjną. Ten tryb jest preferowany w przypadku rozwiązań opartych na sieci Web ze względu na brak automatycznej kontroli jasności ekranu dostępnej w przeglądarkach, co utrudnia działanie koperty trybu pasywnego w rozwiązaniach opartych na sieci Web.

Wartość

Opis

Passive

Wykorzystuje pasywną technikę utrzymania, która nie wymaga żadnych dodatkowych akcji od użytkownika. Wymaga normalnego oświetlenia wewnętrznego i wysokiej jasności ekranu w celu uzyskania optymalnej wydajności. W związku z tym ten tryb ma wąskią kopertę operacyjną i nie będzie odpowiedni dla scenariuszy, które wymagają, aby użytkownik końcowy był w jasnych warunkach oświetleniowych. Uwaga: jest to jedyny obsługiwany tryb rozwiązania Dla urządzeń przenośnych (iOS i Android).

PassiveActive

Ten tryb wykorzystuje hybrydową technikę pasywnej lub aktywnej aktywności, która wymaga współpracy użytkowników. Jest zoptymalizowany pod kątem wymagania aktywnego ruchu tylko w warunkach nieoptymalnych oświetlenia. W przeciwieństwie do trybu pasywnego ten tryb nie ma ograniczeń oświetlenia, a tym samym oferuje szerszą kopertę operacyjną. Ten tryb jest preferowany w przypadku rozwiązań opartych na sieci Web ze względu na brak automatycznej kontroli jasności ekranu dostępnej w przeglądarkach, co utrudnia działanie koperty trybu pasywnego w rozwiązaniach opartych na sieci Web.

LivenessWithVerifyOutputs

Objekt

Dane wyjściowe weryfikacji twarzy.

Nazwa	Typ	Opis
isIdentical	boolean	Czy docelowa twarz na żywo i porównanie twarzy są zgodne.
matchConfidence	number (float) minimum: 0 maximum: 1	Docelowa twarz na żywo twarzy i porównanie obrazu weryfikacja twarzy.

LivenessWithVerifyReference

Objekt

Szczegóły twarzy na potrzeby weryfikacji.

Nazwa	Typ	Opis
faceRectangle	FaceRectangle	Region twarzy, w którym utworzono klasyfikację obrazu porównania.
qualityForRecognition	QualityForRecognition	Jakość obrazu twarzy do rozpoznawania.
referenceType	ImageType	Typ obrazu zawierający prostokąt twarzy, na którym utworzono klasyfikację liveness.

LivenessWithVerifyResult

Objekt

Wyniki liveness z weryfikacją wywołania.

Nazwa	Typ	Opis
digest	string	Serwer obliczył skrót dla tego żądania. Jeśli raportowany skrót klienta różni się od skrótu obliczeniowego serwera, integralność komunikatów między klientem a usługą została naruszona, a wynik nie powinien być zaufany. Aby uzyskać więcej informacji, zobacz przewodniki dotyczące sposobu wykorzystania tej wartości w celu zabezpieczenia kompleksowego rozwiązania.
livenessDecision	LivenessDecision	Klasyfikacja liveness dla docelowej twarzy.
sessionImageId	string	Identyfikator obrazu żądania sesji.
targets	LivenessDecisionTargets	Elementy docelowe używane do klasyfikacji dostępności.
verifyImageHash	string	Skrót sha256 obrazu weryfikacji w żądaniu.
verifyResult	LivenessWithVerifyOutputs	Dane wyjściowe weryfikacji twarzy. Dostępne tylko wtedy, gdy żądanie jest aktywne z weryfikacją.

LivenessWithVerifySession

Objekt

Wynik sesji wykrywania aktualności przy użyciu weryfikacji.

Nazwa	Typ	Opis
authToken	string	Token elementu nośnego w celu zapewnienia uwierzytelniania zestawu SDK przetwarzania obrazów działającego w aplikacji klienckiej. Ten token elementu nośnego ma ograniczone uprawnienia do wykonywania tylko wymaganej akcji i wygasa po upływie czasu wygaśnięcia. Można go również przeprowadzić inspekcję.
modelVersion	LivenessModel	Wersja modelu używana do klasyfikacji aktualności. Jest to opcjonalny parametr i jeśli nie zostanie określony, zostanie wybrana najnowsza obsługiwana wersja modelu
results	LivenessWithVerifySessionResults	Wyniki liveness z weryfikacją sesji.
sessionId	string	Unikatowy identyfikator do odwołowania się do tej sesji.
status	OperationState	Bieżący stan sesji.

LivenessWithVerifySessionAttempt

Objekt

Żywość z próbą weryfikacji sesji.

Nazwa	Typ	Opis
attemptId	integer (int32)	Identyfikator próby, zacznij od 1.
attemptStatus	OperationState	Stan próby.
error	LivenessError	Błąd działania z wywołaniem weryfikacji będzie mieć wartość null, jeśli wystąpi wynik.
result	LivenessWithVerifyResult	Wynik działania z wywołaniem weryfikacji będzie mieć wartość null, jeśli wystąpi błąd.

LivenessWithVerifySessionResults

Objekt

Wyniki liveness z weryfikacją sesji.

Nazwa	Typ	Opis
attempts	LivenessWithVerifySessionAttempt[]	Próbujesz podjąć próbę danych podstawowej aktualności z weryfikacją wywołania z sesją.
verifyReferences	LivenessWithVerifyReference[]	Odwołania używane do weryfikacji twarzy.

OperationState

Wyliczanie

Bieżący stan sesji.

Wartość	Opis
Canceled	Operacja została anulowana przez użytkownika.
Failed	Operacja nie powiodła się.
NotStarted	Operacja nie została uruchomiona.
Running	Operacja jest w toku.
Succeeded	Operacja została ukończona pomyślnie.

QualityForRecognition

Wyliczanie

Wskazuje jakość obrazu do rozpoznawania.

Wartość	Opis
high	Wysoka jakość.
low	Niska jakość.
medium	Średnia jakość.

Udostępnij za pośrednictwem

Liveness Session Operations - Create Liveness With Verify Session

Parametry identyfikatora URI

Odpowiedzi

Zabezpieczenia

Ocp-Apim-Subscription-Key

AADToken

Zakresy

Przykłady

Create LivenessWithVerify Session

Przykładowe żądanie

Przykładowa odpowiedź

Definicje

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition