受動的生体検知 (FaceLiveness) は、API 操作に送信された、事前にキャプチャされた顔イメージが実在の顔であるかどうかを判断するサービスです。このアルゴリズムは、主に画面のリプレイや印刷された写真などの基本的ななりすまし攻撃を検出します。このサービスは、低リスクのビジネスシナリオや、オフラインの顔認識ソフトウェア開発キット (SDK) との併用に適しています。ビジネスで高レベルのセキュリティを必要とする ID 検証が必要な場合は、App SDK または Web SDK を統合してください。
API の説明
API 操作名: FaceLiveness
リクエストメソッド: HTTPS POST
説明: 顔イメージに対して生体検知を実行します。
QPS 制限: この API は、排他的な秒間クエリ数 (QPS) 制限の対象となります。詳細については、「ID Verification サーバーサイド API の QPS 制限」をご参照ください。
エンドポイント:
説明内部ネットワークは、同一リージョン内の Alibaba Cloud プロダクト間のプライベート通信ネットワークです。アプリケーションサーバが Alibaba Cloud リージョンにデプロイされている場合、内部エンドポイントを使用して ID Verification サービスにアクセスできます。これにより、より安全で安定したネットワーク接続が提供されます。
中国 (香港)
パブリックエンドポイント:
cloudauth-intl.cn-hongkong.aliyuncs.com同一リージョン内の内部エンドポイント:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
オンラインでのテストと統合
デバッグと統合を行う前に、「OpenAPI Explorer を使用してサーバーサイド API 操作をデバッグおよび統合する」ドキュメントをお読みください。このドキュメントでは、OpenAPI プラットフォームで API 操作を呼び出す方法と、SDK およびそのサンプルコードを取得する方法について説明します。
この操作は OpenAPI Explorer で実行してテストし、SDK サンプルコードを生成できます。
イメージフォーマットの要件
イメージフォーマット: JPG、JPEG、または PNG。
イメージサイズ: 推奨 50 KB~100 KB、最大 1 MB。
イメージ解像度: 解像度は 640 × 480 ピクセル (高さ × 幅) から 1920 × 1080 ピクセルの間である必要があります。短辺を 720 ピクセルにスケーリングし、圧縮率を 0.9 より大きくすることをお勧めします。写真の高さは幅よりも大きくする必要があります。幅が高さよりも大きいイメージは、検出結果に影響を与える可能性があります。
説明パラメーターを base64 フォーマットで渡す場合、1 MB のデータ送信制限内に収まるように、元のイメージサイズが 0.6 MB を超えないようにしてください。
イメージ品質の推奨事項:
顔は完全で、鮮明で、遮られていない必要があります。被写体はカメラにまっすぐ向いている必要があります。前面カメラで撮影したイメージを使用することをお勧めします。
顔がイメージ領域の 60% 以上を占めるようにしてください。顔が小さいと検出精度が低下します。
イメージに複数の顔が含まれている場合、アルゴリズムはデフォルトで最大の顔をトリミングします。複数の顔を含むイメージの使用は避けることをお勧めします。
リクエストパラメーター
次のいずれかのパラメーターを使用してイメージを指定できます。
FacePictureBase64
FacePictureUrl
名前 | タイプ | 必須 | 説明 | 例 |
ProductCode | String | はい | 使用するプロダクトソリューション。受動的生体検知 API を使用するには、値を FACE_LIVENESS_MIN に設定します。 | FACE_LIVENESS_MIN |
SceneCode | String | いいえ | カスタム認証シナリオ ID。この ID を使用して、コンソールで関連レコードをクエリできます。ID は最大 10 文字で、文字、数字、アンダースコア (_) を含めることができます。 | 1234567890 |
MerchantBizId | String | はい | カスタムの一意のビジネス識別子。この識別子を使用して、問題を追跡およびトラブルシューティングできます。識別子は最大 32 文字で、文字と数字を含めることができます。識別子がユニークであることを確認してください。 説明 Alibaba Cloud サーバーは、この値の一意性をチェックしません。追跡を改善するために、この値がユニークであることを確認してください。 | e0c34a77f5ac40a5aa5e6ed20c35**** |
MerchantUserId | String | はい | カスタムユーザー ID または特定のユーザーの別の識別子 (携帯電話番号やメールアドレスなど)。セキュリティのため、ハッシュ化するなどして、この値を事前に非特定化してください。 | 123456789 |
FacePictureBase64 | String | はい | Base64 エンコードされたイメージ。このパラメーターを使用して顔イメージを渡す場合は、イメージサイズを確認してください。大きすぎるイメージは渡さないでください。 | base64 |
FacePictureUrl | String | はい | 縦向きイメージの URL。URL は、インターネット経由でアクセス可能な HTTP または HTTPS リンクである必要があります。 | https://*** |
FaceQuality | String | いいえ | 顔イメージの品質スコアを返すかどうかを指定します。デフォルト値は F です。
| F |
Crop | String | いいえ | 顔イメージのトリミングを許可するかどうかを指定します。デフォルト値は F です。
| F |
Occlusion | String | いいえ | オクルージョン検出を有効にするかどうかを指定します。デフォルト値は F です。
| F |
応答パラメーター
名前 | タイプ | 説明 | 例 | |
HTTP ステータスコード | Integer | HTTP ステータスコード。 | 200 | |
HTTP Body | RequestId | String | リクエスト ID。 | 130A2C10-B9EE-4D84-88E3-5384FF0**** |
Result.TransactionId | String | 認証プロセス全体のユニーク ID。 | hksb7ba1b28130d24e015d694361**** | |
Code | String | Success | ||
Message | String | 応答コードの詳細な説明。 | Success | |
Result.Passed | String | 認証結果。有効な値:
| Y | |
Result.SubCode | String | 検証結果に対応するコード。詳細については、「ResultObject.SubCode エラーコード」をご参照ください。 | 200 | |
Result.ExtFaceInfo | String | 受動的生体検知の結果。値は JSON フォーマットです。詳細については、「ExtFaceInfo」をご参照ください。 | | |
応答コード
HTTP ステータスコード | コード | メッセージ |
200 | Success | リクエストは成功しました。 |
400 | MissingParameter | パラメーターを空にすることはできません。 |
InvalidParameter | 無効なパラメーターです。 | |
401 | UnqualifiedPhoto | アップロードされたイメージは読み取れないか、イメージの解像度が要件を満たしていません。イメージを変更することをお勧めします。 写真が鮮明で、露出が正常で、遮蔽物がなく完全で、大幅な角度のずれがないことを確認してください。 |
DataDuplication | Base64 エンコードされたイメージと URL イメージアドレスの両方が提供されています。これらのパラメーターのいずれか 1 つだけを選択してください。 | |
ToolargeImage | イメージサイズが大きすぎます。イメージを圧縮するか、アップロード方法を変更することをお勧めします。 | |
DownloadTimeout | URL イメージのダウンロードがタイムアウトしました。 | |
NoFaceDetected | アップロードされたイメージで顔が検出されませんでした。 | |
403 | Forbidden.RAMUserAccessDenied | RAM ユーザーに AliyunAntCloudAuthFullAccess 権限を付与する必要があります。詳細については、「RAM ユーザーにサービスへのアクセスを承認する」をご参照ください。 |
Forbidden.AccountAccessDenied | ID Verification を有効にし、アカウントに支払い遅延がないことを確認してください。 | |
Throttling.Api | API リクエストはスロットリングのためにブロックされています。 | |
500 | InternalError | 内部システムエラー。トラブルシューティングのためにエンジニアにフィードバックを提供してください。 |
ResultObject.SubCode エラーコード
エラーコード | 課金対象 | 説明と提案 |
200 | はい | 認証に合格しました。 |
205 | はい | 生体検知には固有のリスクがあります。 |
ExtFaceInfo
名前 | タイプ | 説明 | 例 |
faceQualityScore | Double | 任意。ライブ顔の品質スコア。値の範囲は 0~100 です。 | 88.62 |
occlusionResult | String | 任意。顔が遮蔽されているかどうかを示します。Y は顔が遮蔽されていることを意味します。N は顔が遮蔽されていないことを意味します。 | N |
faceAttack | String | キャプチャされた顔になりすまし攻撃が検出されたかどうかを示します。Y は攻撃が検出されたことを意味します。N は攻撃が検出されなかったことを意味します。 | N |
faceAge | String | イメージ内の人物の予測年齢。予測が失敗し、値が空になる場合があります。 | 30 |
faceGender | String | イメージ内の人物の予測される性別。予測が失敗し、値が空になる場合があります。
| M |