Liveness Session Operations - Create Liveness With Verify Session

サービス:: Azure AI Services

API バージョン:: v1.2

検証を使用して新しいライブネスセッションを作成します。セッションの作成時に検証イメージを指定します。
セッションは、開発者がリソースへのフルアクセスを許可せずにライブネス検出のみを実行するようにクライアントデバイスを承認するクライアントデバイスシナリオに最適です。作成されたセッションの有効期間は限られており、アクセスが期限切れになる前にクライアントが目的のアクションを実行することを承認するだけです。

アクセス許可に含まれるもの...

- トークンの有効期間は 10 分です。

Note

- クライアントアクセスは、セッションの検証を使用してライブネスの削除操作を使用してセッションを削除することで取り消すことができます。
- 結果を取得するには、Get Liveness With Verify Session を使用します。
- クライアントがリソースに対して行った個々の要求を監査するには、List Liveness With Verify Session Audit Entries を使用します。

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

URI パラメーター

名前	/	必須	型	説明
livenessOperationMode	formData	True	LivenessOperationMode	クライアントが従う必要があるライブネスモードの種類。
verifyImage	formData	True	file	検証用のイメージストリーム。このパーツの Content-Disposition ヘッダーフィールドにはファイル名が必要です。
authTokenTimeToLiveInSeconds	formData		integer (int32) minimum: 60 maximum: 86400	セッションが続く秒数。範囲は 60 ~ 86400 秒です。既定値は 600 です。
deviceCorrelationId	formData		string	各エンドユーザーデバイスごとの一意の Guid。これはレート制限と反ハンマーを提供するためです。この要求で 'deviceCorrelationIdSetInClient' が true の場合、この 'deviceCorrelationId' は null である必要があります。
deviceCorrelationIdSetInClient	formData		boolean	クライアントが Vision SDK を介して独自の 'deviceCorrelationId' を設定できるかどうかを指定します。既定値は false で、この要求本文で 'deviceCorrelationId' を設定する必要があります。
enableSessionImage	formData		boolean	セッションイメージを格納するかどうか。
livenessModelVersion	formData		LivenessModel	ライブネス分類に使用されるモデルバージョン。これは省略可能なパラメーターであり、これが指定されていない場合は、サポートされている最新のモデルバージョンが選択されます
returnVerifyImageHash	formData		boolean	検証イメージハッシュを返すかどうか。
verifyConfidenceThreshold	formData		number (float) minimum: 0 maximum: 1	顔検証の信頼度のしきい値。詳細については、ドキュメントを参照してください。 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 バージョン
endpoint	path	True	string (uri)	サポートされている Cognitive Services エンドポイント (プロトコルとホスト名。例: https://{resource-name}.cognitiveservices.azure.com)。

応答

名前	型	説明
200 OK	LivenessWithVerifySession	呼び出しが成功すると、クライアントデバイスのセッションが作成され、限られた目的と時間のためにクライアントアプリケーションで使用するための承認トークンが提供されます。
Other Status Codes	FaceErrorResponse	予期しないエラー応答。ヘッダー x-ms-error-code: string

名前

型

説明

200 OK

LivenessWithVerifySession

呼び出しが成功すると、クライアントデバイスのセッションが作成され、限られた目的と時間のためにクライアントアプリケーションで使用するための承認トークンが提供されます。

Other Status Codes

FaceErrorResponse

予期しないエラー応答。

ヘッダー

x-ms-error-code: string

セキュリティ

Ocp-Apim-Subscription-Key

Azure AI Face サブスクリプションの秘密鍵。

型: apiKey
/: header

AADToken

Azure Active Directory OAuth2 フロー

型: oauth2
フロー: accessCode
Authorization URL (承認 URL): https://api.example.com/oauth2/authorize
Token URL (トークン URL): https://api.example.com/oauth2/token

スコープ

名前	説明
https://cognitiveservices.azure.com/.default

例

Create LivenessWithVerify Session

要求のサンプル

HTTP

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

応答のサンプル

状態コード:: 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"
      }
    ]
  }
}

定義

名前	説明
FaceError	エラーオブジェクト。 Face サービスによって返されるエラーコードとメッセージの詳細については、次のリンクを参照してください: https://aka.ms/face-error-codes-and-messages。
FaceErrorResponse	エラーの詳細を含む応答。
FaceRectangle	顔が見つかる四角形。
ImageType	イメージの種類。
LivenessColorDecisionTarget	ライブネス分類に使用されるカラー画像のターゲット。
LivenessDecision	ライブネス分類の結果。
LivenessDecisionTargets	ライブネス分類に使用されるターゲット。
LivenessError	ライブネス分類のエラー。
LivenessModel	ライブネス分類に使用されるモデルバージョン。
LivenessOperationMode	クライアントのエンドユーザーエクスペリエンスを促進するライブネス操作モード。
LivenessWithVerifyOutputs	顔検証の出力。
LivenessWithVerifyReference	検証用の顔の詳細。
LivenessWithVerifyResult	検証呼び出しでのライブネスの結果。
LivenessWithVerifySession	検証を使用してライブ状態を検出したセッション結果。
LivenessWithVerifySessionAttempt	セッションの検証の試行を伴うライブネス。
LivenessWithVerifySessionResults	検証セッションでのライブ性の結果。
OperationState	セッションの現在の状態。
QualityForRecognition	認識用の画像の品質を示します。

FaceError

Object

エラーオブジェクト。 Face サービスによって返されるエラーコードとメッセージの詳細については、次のリンクを参照してください: https://aka.ms/face-error-codes-and-messages。

名前	型	説明
code	string	サーバー定義の一連のエラーコードの 1 つ。
message	string	エラーの人間が判読できる表現。

FaceErrorResponse

Object

エラーの詳細を含む応答。

名前	型	説明
error	FaceError	エラーオブジェクト。

FaceRectangle

Object

顔が見つかる四角形。

名前	型	説明
height	integer (int32)	四角形の高さ (ピクセル単位)。
left	integer (int32)	画像から四角形の左端までの距離 (ピクセル単位)。
top	integer (int32)	画像が四角形の上端までの場合の上端からの距離 (ピクセル単位)。
width	integer (int32)	四角形の幅 (ピクセル単位)。

ImageType

列挙

イメージの種類。

値	説明
Color	カラー画像。
Infrared	赤外線画像。
Depth	深度画像。

LivenessColorDecisionTarget

Object

ライブネス分類に使用されるカラー画像のターゲット。

名前	型	説明
faceRectangle	FaceRectangle	ライブネス分類が行われた顔領域。

LivenessDecision

列挙

ライブネス分類の結果。

値	説明
uncertain	アルゴリズムでは、ターゲットの顔を実際の顔またはスプーフィングとして分類できませんでした。
realface	このアルゴリズムでは、ターゲットの顔が実際の顔として分類されています。
spoofface	このアルゴリズムでは、ターゲットの顔がスプーフィングとして分類されています。

LivenessDecisionTargets

Object

ライブネス分類に使用されるターゲット。

名前	型	説明
color	LivenessColorDecisionTarget	ライブネス分類に使用されるカラー画像のターゲット。

LivenessError

Object

ライブネス分類のエラー。

名前	型	説明
code	string	エラーコード。
message	string	エラーメッセージ。
targets	LivenessDecisionTargets	ライブネス分類に使用されるターゲット。

LivenessModel

列挙

ライブネス分類に使用されるモデルバージョン。

値	説明
2024-11-15

LivenessOperationMode

列挙

クライアントのエンドユーザーエクスペリエンスを促進するライブネス操作モード。

値	説明
Passive	ユーザーからの追加のアクションを必要としないパッシブライブネス手法を利用します。最適なパフォーマンスを得るには、通常の屋内照明と高い画面輝度が必要です。したがって、このモードは運用エンベロープが狭く、エンドユーザーが明るい照明条件である必要があるシナリオには適していません。注: これは Mobile (iOS および Android) ソリューションでサポートされている唯一のモードです。
PassiveActive	このモードでは、ユーザーの協力を必要とするハイブリッドパッシブまたはアクティブなライブネス手法を利用します。これは、最適でない照明条件下でのみアクティブなモーションを必要とするように最適化されています。パッシブモードとは異なり、このモードには照明の制限がないため、より広範な運用エンベロープが提供されます。このモードは、Web ベースのソリューションでパッシブモードの運用エンベロープを妨げるブラウザーで使用できる自動画面の明るさ制御がないため、Web ベースのソリューションで推奨されます。

値

説明

Passive

ユーザーからの追加のアクションを必要としないパッシブライブネス手法を利用します。最適なパフォーマンスを得るには、通常の屋内照明と高い画面輝度が必要です。したがって、このモードは運用エンベロープが狭く、エンドユーザーが明るい照明条件である必要があるシナリオには適していません。注: これは Mobile (iOS および Android) ソリューションでサポートされている唯一のモードです。

PassiveActive

このモードでは、ユーザーの協力を必要とするハイブリッドパッシブまたはアクティブなライブネス手法を利用します。これは、最適でない照明条件下でのみアクティブなモーションを必要とするように最適化されています。パッシブモードとは異なり、このモードには照明の制限がないため、より広範な運用エンベロープが提供されます。このモードは、Web ベースのソリューションでパッシブモードの運用エンベロープを妨げるブラウザーで使用できる自動画面の明るさ制御がないため、Web ベースのソリューションで推奨されます。

LivenessWithVerifyOutputs

Object

顔検証の出力。

名前	型	説明
isIdentical	boolean	ターゲットのライブネス顔と比較画像の顔が一致するかどうか。
matchConfidence	number (float) minimum: 0 maximum: 1	対象顔のライブネス顔と比較画像顔検証信頼度。

LivenessWithVerifyReference

Object

検証用の顔の詳細。

名前	型	説明
faceRectangle	FaceRectangle	比較画像の分類が行われた顔領域。
qualityForRecognition	QualityForRecognition	認識のための顔画像の品質。
referenceType	ImageType	ライブネス分類が行われた顔の四角形を含む画像の種類。

LivenessWithVerifyResult

Object

検証呼び出しでのライブネスの結果。

名前	型	説明
digest	string	この要求のサーバー計算ダイジェスト。クライアントから報告されたダイジェストがサーバー計算ダイジェストと異なる場合、クライアントとサービスの間のメッセージ整合性が損なわれ、結果は信頼されません。詳細については、この値を活用してエンドツーエンドソリューションをセキュリティで保護する方法に関するガイドを参照してください。
livenessDecision	LivenessDecision	ターゲット顔のライブネス分類。
sessionImageId	string	セッション要求のイメージ ID。
targets	LivenessDecisionTargets	ライブネス分類に使用されるターゲット。
verifyImageHash	string	要求内の verify-image の sha256 ハッシュ。
verifyResult	LivenessWithVerifyOutputs	顔検証の出力。要求が検証の有効期間である場合にのみ使用できます。

LivenessWithVerifySession

Object

検証を使用してライブ状態を検出したセッション結果。

名前	型	説明
authToken	string	クライアントアプリケーションで実行されている Vision SDK の認証を提供するベアラートークン。このベアラートークンには、必要なアクションのみを実行するアクセス許可が制限されており、TTL 時間が経過すると有効期限が切れます。監査も可能です。
modelVersion	LivenessModel	ライブネス分類に使用されるモデルバージョン。これは省略可能なパラメーターであり、これが指定されていない場合は、サポートされている最新のモデルバージョンが選択されます
results	LivenessWithVerifySessionResults	検証セッションでのライブ性の結果。
sessionId	string	このセッションを参照する一意の ID。
status	OperationState	セッションの現在の状態。

LivenessWithVerifySessionAttempt

Object

セッションの検証の試行を伴うライブネス。

名前	型	説明
attemptId	integer (int32)	試行 ID。1 から始まります。
attemptStatus	OperationState	試行の状態。
error	LivenessError	検証呼び出しでのライブネスのエラー。結果がある場合は null になります。
result	LivenessWithVerifyResult	検証呼び出しでのライブネスの結果は、エラーがある場合は null になります。

LivenessWithVerifySessionResults

Object

検証セッションでのライブ性の結果。

名前	型	説明
attempts	LivenessWithVerifySessionAttempt[]	セッションとの呼び出しを検証して、基になるライブ性のデータを試行します。
verifyReferences	LivenessWithVerifyReference[]	顔認証に使用される参照。

OperationState

列挙

セッションの現在の状態。

値	説明
NotStarted	操作が開始されていません。
Running	操作が進行中です。
Succeeded	操作が正常に完了しました。
Failed	操作が失敗しました。
Canceled	操作はユーザーによって取り消されました。

QualityForRecognition

列挙

認識用の画像の品質を示します。

値	説明
low	低品質。
medium	中程度の品質。
high	高品質。

次の方法で共有

Liveness Session Operations - Create Liveness With Verify Session

URI パラメーター

応答

セキュリティ

Ocp-Apim-Subscription-Key

AADToken

スコープ

例

Create LivenessWithVerify Session

要求のサンプル

応答のサンプル

定義

FaceError

FaceErrorResponse

FaceRectangle

ImageType

LivenessColorDecisionTarget

LivenessDecision

LivenessDecisionTargets

LivenessError

LivenessModel

LivenessOperationMode

LivenessWithVerifyOutputs

LivenessWithVerifyReference

LivenessWithVerifyResult

LivenessWithVerifySession

LivenessWithVerifySessionAttempt

LivenessWithVerifySessionResults

OperationState

QualityForRecognition