すべてのプロダクト
Search

このプロダクト

    ID Verification:初期化

    ドキュメントセンター

    ID Verification:初期化

    最終更新日:Feb 01, 2026

    このトピックでは、Initialize API 操作を呼び出して顔のライブネス検証リクエストを開始する方法について説明します。

    検証リクエストの開始

    • API 操作：Initialize

    • リクエストメソッド：HTTPS POST

    • 説明：検証フローを開始する前に、この API 操作を呼び出して transactionId を取得します。この ID は、検証リクエスト内のすべての API 操作をリンクします。

    • この 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

    オンラインでのデバッグと統合

    説明

    API 操作をデバッグおよび統合する前に、「OpenAPI Explorer を使用したサーバーサイド API 操作のデバッグと統合」で、API 操作の呼び出し方法、および OpenAPI Explorer での SDK とサンプルコードの取得方法に関する情報をご参照ください。

    この API 操作は OpenAPI Explorer でデバッグできます。また、この操作のサンプル SDK コードを生成することもできます。

    入力画像のフォーマット要件

    • 画像フォーマット：JPG、JPEG、または PNG。

    • 画像サイズ：50 KB から 100 KB を推奨します。最大サイズは 1 MB です。

    • 画像の解像度：解像度は 640 × 480 ピクセル (高さ × 幅) から 1920 × 1080 ピクセルの間である必要があります。短い辺を 720 ピクセルにスケーリングし、圧縮率を 0.9 以上にすることを推奨します。画像の高さは幅よりも大きくする必要があります。幅が高さよりも大きい場合、検出精度が低下する可能性があります。

      説明

      画像を Base64 フォーマットに変換すると、データサイズが増加します。Base64 フォーマットでパラメーターを渡すには、1 MB のデータ転送制限を超えないように、元の画像サイズが 0.6 MB を超えないようにしてください。

    • 画像品質の推奨事項：

      • 画像内の顔は、完全で、鮮明で、遮られていない必要があります。被写体はカメラに正対する必要があります。前面カメラで撮影した顔画像の使用を推奨します。

      • 顔は画像エリアの 60% 以上を占めるようにしてください。顔が小さいと検出精度が低下する可能性があります。

      • 画像に複数の顔がある場合、アルゴリズムはデフォルトで最大の顔を切り抜きます。複数の顔がある画像は避けることを推奨します。

    リクエストパラメーター

    名前

    タイプ

    必須

    説明

    例

    ProductCode

    String

    はい

    使用するプロダクトソリューション。有効な値は FACE_VERIFY のみです。

    FACE_VERIFY

    SceneCode

    String

    いいえ

    検証シナリオのカスタム ID。この ID を使用して、コンソールで関連レコードをクエリできます。ID は最大 10 文字で、英字、数字、アンダースコア (_) を含めることができます。

    1234567890

    MerchantBizId

    String

    はい

    カスタムの一意なビジネス ID。この ID を使用して、問題を追跡およびトラブルシューティングできます。ID は最大 32 文字で、英字と数字を含めることができます。ID が一意であることを確認してください。

    説明

    Alibaba Cloud サーバーはこのフィールドの一意性をチェックしません。追跡を容易にするため、このフィールドの一意性を確保することを強く推奨します。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    はい

    MetaInfo 環境パラメーター。このパラメーターはクライアント SDK を使用して取得します。詳細については、「Android 統合」をご参照ください。

    説明

    戻り値を変更しないでください。そのまま渡してください。

    		 
    {
    "appVersion": "1",
    "bioMetaInfo": "4.1.0:1150****,0",
    "appName": "com.aliyun.antcloudauth",
    "deviceType": "ios",
    "osVersion": "iOS 10.3.2",
    "apdidToken": "",
    "deviceModel": "iPhone9,1"
}

    MerchantUserId

    String

    はい

    特定のユーザーのカスタムユーザー ID またはその他の識別子 (携帯電話番号やメールアドレスなど)。事前にこのフィールドの値を非識別化すること (例えば、値をハッシュ化するなど) を強く推奨します。

    123456789

    FacePictureBase64

    String

    いいえ

    Base64 エンコードされた顔画像。FacePictureBase64 パラメーターを使用して顔画像を渡す場合は、画像サイズを確認してください。大きすぎる画像を渡さないでください。

    /9j/4AAQSkZJRgABAQAASASBC****

    FacePictureUrl

    String

    いいえ

    顔画像の URL。URL は、パブリックネットワーク経由でアクセス可能な HTTP または HTTPS リンクである必要があります。

    説明

    ProductCode が FACE_VERIFY に設定されている場合は、FacePictureBase64 または FacePictureUrl のいずれかを指定する必要があります。

    https://cn-shanghai-aliyun-cloudauth-****.oss-cn-shanghai.aliyuncs.com/verify/****.jpeg

    SecurityLevel

    String

    いいえ

    検証フローの異なるセキュリティレベルを表すモード。有効な値：

    • 01：標準モード。このモードは、デバイス情報の収集に制限がある低脅威シナリオにのみ適用されます。

    • 02：セーフモード。比較的厳格なモード (デフォルト)。

      説明

      • セーフモードでは、SDK の新しい Device Guard モジュールを使用して、デバイス情報に基づいて顔スキャン環境のセキュリティを識別します。これにより、インジェクション攻撃を阻止する能力が効果的に強化されます。このモードを有効にしてください。

      • 開発およびテスト中に、テストデバイスの環境特性により、Device Guard がそれを脅威と評価し、検証の失敗 (Subcode 206) をトリガーする可能性があります。テスト効率を向上させるため、テストフェーズではモードを「01 標準モード」に設定してください。本番稼働時には、検証セキュリティを強化するために「02 セーフモード」に切り替えてください。

    02

    Model

    String

    いいえ

    実行する生体検知のタイプ：

    • LIVENESS：瞬き生体検知 (デフォルト)。

    • PHOTINUS_LIVENESS：瞬き生体検知と色彩生体検知 (PC ではサポートされていません)。

    説明

    サポートされている SDK のバージョンについては、「SDK リリースノート」をご参照ください。

    PHOTINUS_LIVENESS

    DocVideo

    String

    いいえ

    検証ビデオを保存するかどうかを指定します。

    • N：いいえ (デフォルト)。

    • Y：検証中にユーザーの顔スキャンプロセスのビデオ (1〜2 秒のビデオファイル) が収集され、クエリ API 操作を通じて返されます。

    説明

    ビデオファイルはサイズが大きいため、ネットワークが不安定な場合、不可欠な検証画像の転送を優先するためにシステムによって破棄されることがあります。

    N

    CallbackUrl

    String

    いいえ

    検証結果通知用の Webhook アドレス。コールバックリクエストメソッドはデフォルトで GET です。Webhook アドレスは https で始まる必要があります。検証が完了すると、プラットフォームはこのアドレスにコールバックを送信し、自動的に次のフィールドを追加します：

    • transactionId

    • passed

    • subcode

    警告

    • システムは、API 操作が呼び出される前にこのアドレスがアクセス可能かどうかをチェックします。アドレスがパブリックネットワーク経由でアクセスできない場合、400 エラーが返されます。

    • コールバックは検証完了直後に実行されますが、ネットワークの問題により遅延する可能性があります。まずクライアントで検証完了通知を受け取り、その後クエリ API 操作を呼び出して検証詳細を取得することを推奨します。

    https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

    CallbackToken

    String

    いいえ

    生成するセキュリティトークン。リプレイ防止および改ざん防止チェックに使用されます。

    このパラメーターを設定すると、CallbackToken フィールドが CallbackUrl Webhook に含まれます。

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    いいえ

    厳格な顔品質チェックを有効にするかどうかを指定します。

    • Y：はい (デフォルト)

    • N：いいえ

    重要

    • この構成にはクライアントサイド SDK のサポートが必要です。この機能を有効にしても、クライアントサイド SDK に顔品質検出モジュールが統合されていない場合、この構成は無効として扱われます。

    • クライアントサイド SDK はバージョン 1.2.5 以降である必要があります。

    N

    返されるデータ

    名前

    タイプ

    説明

    例

    HTTP ステータスコード

    Integer

    HTTP ステータスコード。

    200

    HTTP ボディ

    RequestId

    String

    リクエスト ID。

    130A2C10-B9EE-4D84-88E3-5384FF0****

    Code

    String

    コードに戻る。

    Success

    Message

    String

    リターンコードの詳細な説明。

    success

    Result.TransactionId

    String

    検証フロー全体の一意の識別子。このフィールドは、課金統計および CheckResult API 操作リクエストの開始に使用されます。

    重要

    • リクエスト中にエラーが発生した場合 (無効なパラメーターなど)、TransactionId は返されません。

    • 現在のビジネスフローのビジネス ID に TransactionId を添付し、サーバーサイドに保存します。CheckResult を呼び出す際には、サーバーサイドのストレージからこの検証 ID を取得して結果クエリを開始します。

    • TransactionId または TransactionUrl を取得した後、30 分以内に検証を完了する必要があります。この期間を過ぎると、ID または URL は自動的に無効になり、検証に使用できなくなります。

    hksb7ba1b28130d24e015d6********

    Result.Protocol

    String

    hksb7ba1b28130d24e015d*********

    リターンコード

    HTTP ステータスコード

    コード

    説明

    200

    Success

    リクエストは成功しました。

    400

    MissingParameter

    パラメーターは空にできません。

    400

    InvalidParameter

    パラメーターが無効です。

    401

    NoFaceDetected

    カスタムソース画像の顔の特徴抽出に失敗しました。別の画像をアップロードしてください。

    401

    UnqualifiedPhoto

    アップロードされた画像が読み取れないか、解像度が要件を満たしていません。画像を交換してください。写真は鮮明で、露出が適切で、完全で、遮るものがなく、被写体の頭が大きく傾いていないことを確認してください。

    401

    ToolargeImage

    画像が大きすぎます。画像を圧縮するか、別のアップロード方法を使用してください。

    401

    DataDuplication

    Base64 またはリンクを使用して画像を渡すこともできます。

    401

    DownloadTimeout

    URL からの画像のダウンロードがタイムアウトしました。

    403

    Forbidden.RAMUserAccessDenied

    Resource Access Management (RAM) ユーザーに AliyunAntCloudAuthFullAccess 権限を付与します。詳細については、「RAM ユーザーへのサービスアクセス権限の付与」をご参照ください。

    403

    Forbidden.AccountAccessDenied

    ID Verification を有効化し、アカウントに支払い遅延がないことを確認してください。

    403

    Throttling.Api

    API 呼び出しがスロットリングにより制限されています。

    500

    InternalError

    内部システムエラーが発生しました。テクニカルサポートに連絡して支援を求めてください。