すべてのプロダクト
Search
ドキュメントセンター

ID Verification:FACE_LIVENESS_MIN

最終更新日:Nov 09, 2025

受動的生体検知 (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 です。

  • T: 返します。

  • F: スコアを返しません。

F

Crop

String

いいえ

顔イメージのトリミングを許可するかどうかを指定します。デフォルト値は F です。

  • T: 許可

  • F: 禁止

F

Occlusion

String

いいえ

オクルージョン検出を有効にするかどうかを指定します。デフォルト値は F です。

  • T: オン。

  • 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: 認証に合格しました。

  • N: 認証に合格しませんでした。

Y

Result.SubCode

String

検証結果に対応するコード。詳細については、「ResultObject.SubCode エラーコード」をご参照ください。

200

Result.ExtFaceInfo

String

受動的生体検知の結果。値は JSON フォーマットです。詳細については、「ExtFaceInfo」をご参照ください。

{
 "faceAttack": "N",
 "faceQualityScore": 88.62,
 "faceOcclusionResult": "N"
}

応答コード

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: 男性

  • F: 女性

M