Liveness Session Operations - Create Liveness With Verify Session

Dienst:: Azure AI Services

API-Version:: v1.2

Erstellen Sie eine neue Liveness-Sitzung mit "verify". Stellen Sie das Überprüfungsbild während der Sitzungserstellung bereit.
Eine Sitzung eignet sich am besten für Clientgeräteszenarien, in denen Entwickler ein Clientgerät autorisieren möchten, nur eine Livenesserkennung durchzuführen, ohne vollzugriff auf ihre Ressource zu gewähren. Erstellte Sitzungen haben eine begrenzte Lebensdauer und autorisieren nur Clients, die gewünschte Aktion auszuführen, bevor der Zugriff abgelaufen ist.

Permissions includes...

- Eine Tokenlebensdauer von 10 Minuten.

Note

- Der Clientzugriff kann widerrufen werden, indem die Sitzung mithilfe des Vorgangs "Liveness mit Sitzung überprüfen" gelöscht wird.
- Verwenden Sie zum Abrufen eines Ergebnisses die Get Liveness With Verify Session.
- Um die einzelnen Anforderungen zu überwachen, die ein Client an Ihrer Ressource vorgenommen hat, verwenden Sie die Listen liveness With Verify Session Audit Entries.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
livenessOperationMode	formData	True	LivenessOperationMode	Der Typ des Livenessmodus, dem der Client folgen soll.
verifyImage	formData	True	file	Der Bilddatenstrom zur Überprüfung. Das Feld "Content-Disposition"-Kopfzeile für diesen Teil muss den Dateinamen aufweisen.
authTokenTimeToLiveInSeconds	formData		integer (int32) minimum: 60 maximum: 86400	Sekunden, für die die Sitzung dauern sollte. Der Bereich beträgt 60 bis 86400 Sekunden. Der Standardwert ist 600.
deviceCorrelationId	formData		string	Eindeutige GUID pro Endbenutzergerät. Dies ist die Bereitstellung von Zinsbegrenzungen und Anti-Hammering. Wenn "deviceCorrelationIdSetInClient" in dieser Anforderung "true" ist, muss diese "deviceCorrelationId" null sein.
deviceCorrelationIdSetInClient	formData		boolean	Gibt an, ob der Client seine eigene "deviceCorrelationId" über das Vision SDK festlegen darf. Der Standardwert ist "false", und "deviceCorrelationId" muss in diesem Anforderungstext festgelegt werden.
enableSessionImage	formData		boolean	Gibt an, ob das Sitzungsbild gespeichert wird.
livenessModelVersion	formData		LivenessModel	Die Modellversion, die für die Livenessklassifizierung verwendet wird. Dies ist ein optionaler Parameter, und wenn dies nicht angegeben ist, wird die neueste unterstützte Modellversion ausgewählt.
returnVerifyImageHash	formData		boolean	Gibt an, ob der Überprüfungsbildhash zurückgegeben wird.
verifyConfidenceThreshold	formData		number (float) minimum: 0 maximum: 1	Schwellenwert für das Vertrauen der Gesichtsüberprüfung. Weitere Details finden Sie in der Dokumentation. 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	API Version
endpoint	path	True	string (uri)	Unterstützte Cognitive Services-Endpunkte (Protokoll und Hostname, z. B. https://{resource-name}.cognitiveservices.azure.com).

Antworten

Name	Typ	Beschreibung
200 OK	LivenessWithVerifySession	Ein erfolgreicher Aufruf erstellt eine Sitzung für ein Clientgerät und stellt ein Autorisierungstoken für die Verwendung durch die Clientanwendung für einen begrenzten Zweck und eine begrenzte Zeit bereit.
Other Status Codes	FaceErrorResponse	Unerwartete Fehlerantwort. Header x-ms-error-code: string

Name

Typ

Beschreibung

200 OK

LivenessWithVerifySession

Ein erfolgreicher Aufruf erstellt eine Sitzung für ein Clientgerät und stellt ein Autorisierungstoken für die Verwendung durch die Clientanwendung für einen begrenzten Zweck und eine begrenzte Zeit bereit.

Other Status Codes

FaceErrorResponse

Unerwartete Fehlerantwort.

Header

x-ms-error-code: string

Sicherheit

Ocp-Apim-Subscription-Key

Der geheime Schlüssel für Ihr Azure AI Face-Abonnement.

Typ: apiKey
In: header

AADToken

Der Azure Active Directory OAuth2-Fluss

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

Create LivenessWithVerify Session

Beispielanforderung

HTTP

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

Beispiel für eine Antwort

Statuscode:: 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"
      }
    ]
  }
}

Definitionen

Name	Beschreibung
FaceError	Das Fehlerobjekt. Ausführliche Informationen zu Fehlercodes und Nachrichten, die vom Face Service zurückgegeben werden, finden Sie unter folgendem Link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Eine Antwort, die Fehlerdetails enthält.
FaceRectangle	Ein Rechteck, in dem ein Gesicht gefunden werden kann.
ImageType	Der Typ des Bilds.
LivenessColorDecisionTarget	Das Ziel des Farbbilds, das für die Livenessklassifizierung verwendet wird.
LivenessDecision	Das Ergebnis der Livenessklassifizierung.
LivenessDecisionTargets	Die für die Livenessklassifizierung verwendeten Ziele.
LivenessError	Der Fehler der Livenessklassifizierung.
LivenessModel	Die Modellversion, die für die Livenessklassifizierung verwendet wird.
LivenessOperationMode	Der Liveness-Vorgangsmodus, um die Endbenutzerumgebung des Clients zu steuern.
LivenessWithVerifyOutputs	Die Ausgabe der Gesichtsüberprüfung.
LivenessWithVerifyReference	Die Details des Gesichts zur Überprüfung.
LivenessWithVerifyResult	Die Ergebnisse der Live-Nutzung mit "Anruf überprüfen".
LivenessWithVerifySession	Sitzungsergebnis der Erkennung von Liveität mit Überprüfung.
LivenessWithVerifySessionAttempt	Die Liveität mit dem Überprüfen des Sitzungsversuchs.
LivenessWithVerifySessionResults	Die Ergebnisse der Liveität mit der Überprüfungssitzung.
OperationState	Der aktuelle Status der Sitzung.
QualityForRecognition	Gibt die Qualität des Bilds für die Erkennung an.

FaceError

Objekt

Das Fehlerobjekt. Ausführliche Informationen zu Fehlercodes und Nachrichten, die vom Face Service zurückgegeben werden, finden Sie unter folgendem Link: https://aka.ms/face-error-codes-and-messages.

Name	Typ	Beschreibung
code	string	Eine serverdefinierte Gruppe von Fehlercodes.
message	string	Eine lesbare Darstellung des Fehlers.

FaceErrorResponse

Objekt

Eine Antwort, die Fehlerdetails enthält.

Name	Typ	Beschreibung
error	FaceError	Das Fehlerobjekt.

FaceRectangle

Objekt

Ein Rechteck, in dem ein Gesicht gefunden werden kann.

Name	Typ	Beschreibung
height	integer (int32)	Die Höhe des Rechtecks in Pixel.
left	integer (int32)	Der Abstand vom linken Rand, wenn das Bild zum linken Rand des Rechtecks in Pixeln angezeigt wird.
top	integer (int32)	Der Abstand vom oberen Rand, wenn das Bild zum oberen Rand des Rechtecks in Pixeln liegt.
width	integer (int32)	Die Breite des Rechtecks in Pixel.

ImageType

Enumeration

Der Typ des Bilds.

Wert	Beschreibung
Color	Color image.
Infrared	Infrared image.
Depth	Depth image.

LivenessColorDecisionTarget

Objekt

Das Ziel des Farbbilds, das für die Livenessklassifizierung verwendet wird.

Name	Typ	Beschreibung
faceRectangle	FaceRectangle	Die Gesichtsregion, in der die Livenessklassifizierung vorgenommen wurde.

LivenessDecision

Enumeration

Das Ergebnis der Livenessklassifizierung.

Wert	Beschreibung
uncertain	Der Algorithmus konnte das Zielgesicht weder als real noch als Spoof klassifizieren.
realface	Der Algorithmus hat das Zielgesicht als real klassifiziert.
spoofface	Der Algorithmus hat das Zielgesicht als Spoof klassifiziert.

LivenessDecisionTargets

Objekt

Die für die Livenessklassifizierung verwendeten Ziele.

Name	Typ	Beschreibung
color	LivenessColorDecisionTarget	Das Ziel des Farbbilds, das für die Livenessklassifizierung verwendet wird.

LivenessError

Objekt

Der Fehler der Livenessklassifizierung.

Name	Typ	Beschreibung
code	string	Der Fehlercode.
message	string	Die Fehlermeldung.
targets	LivenessDecisionTargets	Ziele, die für die Livenessklassifizierung verwendet werden.

LivenessModel

Enumeration

Die Modellversion, die für die Livenessklassifizierung verwendet wird.

Wert	Beschreibung
2024-11-15

LivenessOperationMode

Enumeration

Der Liveness-Vorgangsmodus, um die Endbenutzerumgebung des Clients zu steuern.

Wert	Beschreibung
Passive	Verwendet eine passive Liveness-Technik, die keine zusätzlichen Aktionen des Benutzers erfordert. Erfordert normale Innenbeleuchtung und hohe Bildschirmhelligkeit für optimale Leistung. Und damit hat dieser Modus einen schmalen Betriebsumschlag und eignet sich nicht für Szenarien, die erfordern, dass der Endbenutzer in hellen Lichtverhältnissen sein muss. Hinweis: Dies ist der einzige unterstützte Modus für die Mobile-Lösung (iOS und Android).
PassiveActive	Dieser Modus verwendet eine hybride passive oder aktive Liveness-Technik, die die Zusammenarbeit der Benutzer erfordert. Es ist so optimiert, dass aktive Bewegung nur unter suboptimalen Beleuchtungsbedingungen erforderlich ist. Im Gegensatz zum passiven Modus hat dieser Modus keine Beleuchtungseinschränkungen und bietet somit einen breiteren Betriebsumschlag. Dieser Modus ist auf webbasierten Lösungen vorzuziehen, da keine automatische Bildschirmhelligkeitskontrolle in Browsern verfügbar ist, die den Betriebsumschlag des passiven Modus auf webbasierten Lösungen behindern.

Wert

Beschreibung

Passive

Verwendet eine passive Liveness-Technik, die keine zusätzlichen Aktionen des Benutzers erfordert. Erfordert normale Innenbeleuchtung und hohe Bildschirmhelligkeit für optimale Leistung. Und damit hat dieser Modus einen schmalen Betriebsumschlag und eignet sich nicht für Szenarien, die erfordern, dass der Endbenutzer in hellen Lichtverhältnissen sein muss. Hinweis: Dies ist der einzige unterstützte Modus für die Mobile-Lösung (iOS und Android).

PassiveActive

Dieser Modus verwendet eine hybride passive oder aktive Liveness-Technik, die die Zusammenarbeit der Benutzer erfordert. Es ist so optimiert, dass aktive Bewegung nur unter suboptimalen Beleuchtungsbedingungen erforderlich ist. Im Gegensatz zum passiven Modus hat dieser Modus keine Beleuchtungseinschränkungen und bietet somit einen breiteren Betriebsumschlag. Dieser Modus ist auf webbasierten Lösungen vorzuziehen, da keine automatische Bildschirmhelligkeitskontrolle in Browsern verfügbar ist, die den Betriebsumschlag des passiven Modus auf webbasierten Lösungen behindern.

LivenessWithVerifyOutputs

Objekt

Die Ausgabe der Gesichtsüberprüfung.

Name	Typ	Beschreibung
isIdentical	boolean	Gibt an, ob die Ziel-Liveness-Gesichts- und Vergleichsbild-Gesichtsvergleiche übereinstimmen.
matchConfidence	number (float) minimum: 0 maximum: 1	Das Zielgesichts-Gesicht und das Vergleichsbild der Überprüfungssicherheit.

LivenessWithVerifyReference

Objekt

Die Details des Gesichts zur Überprüfung.

Name	Typ	Beschreibung
faceRectangle	FaceRectangle	Der Gesichtsbereich, in dem die Klassifizierung des Vergleichsbilds vorgenommen wurde.
qualityForRecognition	QualityForRecognition	Qualität des Gesichtsbilds für die Erkennung.
referenceType	ImageType	Der Bildtyp, der das Gesichtsrechteck enthält, auf dem die Livenessklassifizierung vorgenommen wurde.

LivenessWithVerifyResult

Objekt

Die Ergebnisse der Live-Nutzung mit "Anruf überprüfen".

Name	Typ	Beschreibung
digest	string	Der vom Server berechnete Digest für diese Anforderung. Wenn sich der vom Client gemeldete Digest vom vom Server berechneten Digest unterscheidet, wurde die Nachrichtenintegrität zwischen Client und Dienst kompromittiert, und das Ergebnis sollte nicht vertrauenswürdig sein. Weitere Informationen finden Sie in anleitungen zum Nutzen dieses Werts, um Ihre End-to-End-Lösung zu sichern.
livenessDecision	LivenessDecision	Die Livenessklassifizierung für das Zielgesicht.
sessionImageId	string	Die Bild-ID der Sitzungsanforderung.
targets	LivenessDecisionTargets	Ziele, die für die Livenessklassifizierung verwendet werden.
verifyImageHash	string	Der Sha256-Hash des Prüfbilds in der Anforderung.
verifyResult	LivenessWithVerifyOutputs	Die Ausgabe der Gesichtsüberprüfung. Nur verfügbar, wenn die Anforderung live ist und überprüft wird.

LivenessWithVerifySession

Objekt

Sitzungsergebnis der Erkennung von Liveität mit Überprüfung.

Name	Typ	Beschreibung
authToken	string	Bearertoken zum Bereitstellen der Authentifizierung für das Vision SDK, das auf einer Clientanwendung ausgeführt wird. Dieses Bearertoken verfügt über eingeschränkte Berechtigungen, um nur die erforderliche Aktion auszuführen und nach der TTL-Zeit abläuft. Es ist auch auditierbar.
modelVersion	LivenessModel	Die Modellversion, die für die Livenessklassifizierung verwendet wird. Dies ist ein optionaler Parameter, und wenn dies nicht angegeben ist, wird die neueste unterstützte Modellversion ausgewählt.
results	LivenessWithVerifySessionResults	Die Ergebnisse der Liveität mit der Überprüfungssitzung.
sessionId	string	Die eindeutige ID, die auf diese Sitzung verweist.
status	OperationState	Der aktuelle Status der Sitzung.

LivenessWithVerifySessionAttempt

Objekt

Die Liveität mit dem Überprüfen des Sitzungsversuchs.

Name	Typ	Beschreibung
attemptId	integer (int32)	Die Versuchs-ID, beginnen Sie mit 1.
attemptStatus	OperationState	Der Status des Versuchs.
error	LivenessError	Der Fehler der Liveität mit dem Überprüfungsaufruf ist null, wenn das Ergebnis vorliegt.
result	LivenessWithVerifyResult	Das Ergebnis der Liveität mit dem Überprüfungsaufruf ist null, wenn ein Fehler auftritt.

LivenessWithVerifySessionResults

Objekt

Die Ergebnisse der Liveität mit der Überprüfungssitzung.

Name	Typ	Beschreibung
attempts	LivenessWithVerifySessionAttempt[]	Die Versuchtdaten der zugrunde liegenden Liveität mit dem Überprüfen des Anrufs mit der Sitzung.
verifyReferences	LivenessWithVerifyReference[]	Die für die Gesichtsüberprüfung verwendeten Verweise.

OperationState

Enumeration

Der aktuelle Status der Sitzung.

Wert	Beschreibung
NotStarted	Der Vorgang wurde nicht gestartet.
Running	Der Vorgang wird ausgeführt.
Succeeded	Der Vorgang wurde erfolgreich abgeschlossen.
Failed	Fehler beim Vorgang.
Canceled	Der Vorgang wurde vom Benutzer abgebrochen.

QualityForRecognition

Enumeration

Gibt die Qualität des Bilds für die Erkennung an.

Wert	Beschreibung
low	Low quality.
medium	Medium quality.
high	High quality.

Freigeben über

Liveness Session Operations - Create Liveness With Verify Session

URI-Parameter

Antworten

Sicherheit

Ocp-Apim-Subscription-Key

AADToken

Bereiche

Beispiele

Create LivenessWithVerify Session

Beispielanforderung

Beispiel für eine Antwort

Definitionen

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition