すべてのプロダクト
Search

このプロダクト

    ID Verification:Initialize

    ドキュメントセンター

    ID Verification:Initialize

    最終更新日:Feb 08, 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.ap-southeast-1.aliyuncs.com

      • 内部ネットワーク: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

      インドネシア

      • パブリックネットワーク: cloudauth-intl.ap-southeast-5.aliyuncs.com

      • 内部ネットワーク: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

      中国 (香港)

      • パブリックネットワーク: cloudauth-intl.cn-hongkong.aliyuncs.com

      • 内部ネットワーク: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

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

    説明

    API オペレーションをデバッグして統合する前に、API オペレーションの呼び出し方法、および OpenAPI Explorer で SDK とサンプルコードを取得する方法については、「OpenAPI Explorer を使用したサーバーサイド API オペレーションのデバッグと統合」をご参照ください。

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

    リクエストパラメーター

    名前

    タイプ

    必須

    説明

    例

    ProductCode

    String

    はい

    統合するプロダクトソリューション。有効な値は FACE_IDU のみです。

    FACE_IDU

    SceneCode

    String

    いいえ

    カスタム認証シナリオ ID。この ID を使用して、後でコンソールで関連レコードをクエリできます。10文字、数字、またはアンダースコアの組み合わせをサポートします。

    1234567890

    MetaInfo

    String

    はい

    MetaInfo 環境パラメーター。クライアント SDK を介して getMetaInfo() 関数を呼び出して取得します。MetaInfo の取得方法の詳細については、対応するプラットフォームのクライアント統合ドキュメントをご参照ください。

    説明

    戻り値を変更しないでください。直接渡してください。

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

    SecurityLevel

    String

    いいえ

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

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

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

      説明

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

      • 開発およびテスト中に、テストデバイスの環境特性により、Device Guard がそれを脅威と評価し、認証失敗 (サブコード 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 コールバックに含まれます。

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    いいえ

    厳格な顔品質検出を有効にするかどうか:

    • Y: 有効 (デフォルト)。

    • N: 無効。

    重要

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

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

    N

    VerifyModel

    String

    いいえ

    認証タイプ:

    • 0: 取得モード。

      • 機能: 指定された顔データベースを渡します。ユーザーがクライアントサイドの顔認識アクションを完了すると、システムは指定された顔データベースにその顔イメージがすでに含まれているかどうかを自動的に取得します。

      • 推奨シナリオ: 重複登録が許可されていない実在人物のアカウント作成。

    • 1 (デフォルト): 検証モード。

      • 機能: 指定された顔イメージを渡します。ユーザーがクライアントサイドの顔認識アクションを完了すると、システムは指定された顔と一致するかどうかを自動的に検証します。

      • 推奨シナリオ: ログイン、アカウント情報変更、およびオペレーターの ID の認証が必要なその他のシナリオ。

    • 2: 包括モード。

      • 機能: 指定された顔データベースと顔イメージの両方を渡します。ユーザーがクライアントサイドの顔認識アクションを完了すると、システムは指定された顔データベースにその顔イメージがすでに含まれているかどうか、およびそれが指定された人物であるかどうかを自動的に取得します。

      • 推奨シナリオ: 新規ユーザーとオペレーターの ID の認証が必要なシナリオ。

    0

    FaceGroupCodes

    String

    いいえ

    顔グループを作成する際に、ID Verification コンソールでコードを取得します。一度にクエリできる顔グループは最大10個です。複数の顔グループコードを指定する場合は、カンマで区切ってください。

    説明

    VerifyModel = 1 または 2 の場合に必須です。

    sg*****xta，s*****uk3j

    TargetFacePicture

    String

    いいえ

    顔写真の Base64 エンコーディング。

    比較元として信頼できる顔イメージを参照します。このパラメーターはオプションです。

    説明

    VerifyModel = 1 または 2 の場合に必須です。

    -

    TargetFacePictureUrl

    String

    いいえ

    顔イメージの URL。パブリックネットワーク経由でアクセス可能な HTTP または HTTPS リンクです。

    -

    MerchantUserId

    String

    はい

    カスタム一意ユーザー ID、または携帯電話番号やメールボックスアドレスなど、特定のユーザーを識別できるその他の識別子。

    説明

    このフィールドの値を、ハッシュ化するなどして事前非識別化し、その一意性を維持することを強く推奨します。

    123456789

    AutoRegistration

    String

    いいえ

    検証成功時に指定された顔データベースに自動登録するかどうか:

    • 0: 自動登録。

    • 1 (デフォルト): 登録しない。

    0

    FaceRegisterGroupCode

    String

    いいえ

    顔の自動登録が有効で、複数の顔データベースが存在する場合、このパラメーターを介して指定された顔データベースコードを渡します。

    sg*****xta

    ReturnFaces

    String

    いいえ

    マッチングしきい値を超える複数の顔が存在する場合、このパラメーターを使用して返される顔の数をカスタマイズします。

    デフォルトでは 1 を返します。最大 5 をサポートします。

    説明

    このパラメーターはVerifyModel = 1 の場合は有効になりません。

    1

    FaceVerifyThreshold

    String

    いいえ

    顔検証しきい値。

    説明

    予約済みフィールドであり、まだ利用できません。

    0.4

    戻りデータ

    名前

    タイプ

    説明

    例

    HTTP Status Code

    Integer

    HTTP ステータスコード。

    200

    HTTP Body

    RequestId

    String

    リクエスト ID。

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

    Code

    String

    レスポンスコード。

    Success

    Message

    String

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

    success

    Result.TransactionId

    String

    全認証フローの一意の識別子。このフィールドは、課金統計および CheckResult API オペレーションリクエストの開始に使用されます。

    重要

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

    • TransactionId を現在のビジネスフローのビジネス ID にアタッチし、サーバーサイドに保存します。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

    内部システムエラーが発生しました。テクニカルサポートにお問い合わせください。