すべてのプロダクト
Search

このプロダクト

    ID Verification:初期化

    ドキュメントセンター

    ID Verification:初期化

    最終更新日:Nov 09, 2025

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

    認証リクエストの開始

    • API 操作: Initialize

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

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

    • QPS 制限: この 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

    オンラインでのテストと統合

    説明

    デバッグと統合を行う前に、「OpenAPI Explorer を使用してサーバーサイド API 操作をデバッグおよび統合する」ドキュメントをお読みください。このドキュメントでは、OpenAPI プラットフォームで API 操作を呼び出す方法と、SDK およびそのサンプルコードを取得する方法について説明しています。

    この API 操作は OpenAPI Explorer を使用して実行およびデバッグし、SDK コード例を生成できます。

    リクエストパラメーター

    名前

    タイプ

    必須

    説明

    例

    ProductCode

    String

    はい

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

    FACE_IDU

    SceneCode

    String

    いいえ

    認証シナリオのカスタム ID。この 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 モジュールを使用して、顔スキャン環境とデバイスのセキュリティを識別します。これにより、インジェクション攻撃の迎撃が効果的に強化されます。このモードを選択することを強く推奨します。

    02

    Model

    String

    いいえ

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

    • LIVENESS (デフォルト): まばたきアクション生体検知。

    • PHOTINUS_LIVENESS: まばたきアクション生体検知とカラフル生体検知によるデュアル検知。

    • PHOTINUS_FAR_NEAR_LIVENESS: まばたきアクション + 遠近 + カラフル生体検知。

      (App SDK または App SDK に基づく Flutter 統合でのみサポート)

    説明

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

    • PC はカラフル生体検知によるデュアル検知をサポートしていません。

    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 (デフォルト): 検証モード

      • 特徴: 顔画像を提供します。ユーザーがクライアントで顔認識アクションを完了すると、システムはユーザーの顔が提供された画像と一致するかどうかを自動的に検証します。

      • 推奨シナリオ: ログイン、アカウント情報の変更、および本人確認が必要なその他のシナリオ。

    • 2: 総合モード

      • 特徴: 顔データベースと顔画像の両方を提供します。ユーザーがクライアントで顔認識アクションを完了すると、システムはユーザーの顔画像がデータベースに存在するかどうか、および提供された画像と一致するかどうかを自動的に確認します。

      • 推奨シナリオ: 新規ユーザーの検証と本人確認が必要なシナリオ。

    0

    FaceGroupCodes

    String

    いいえ

    コンソールで作成した顔データベースのコード。一度に最大 10 個の顔データベースをクエリできます。複数のデータベースコードはカンマ (,) で区切ります。

    説明

    このパラメーターは、VerifyModel が 1 または 2 に設定されている場合に必須です。

    sg*****xta,s*****uk3j

    TargetFacePicture

    String

    いいえ

    Base64 エンコードされたポートレート写真。

    これは比較用の信頼できるソース顔画像です。このパラメーターはオプションです。

    説明

    このパラメーターは、VerifyModel が 1 または 2 に設定されている場合に必須です。

    -

    TargetFacePictureUrl

    String

    いいえ

    ポートレートイメージの URL。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 ステータスコード

    Integer

    HTTP ステータスコード。

    200

    レスポンスボディ

    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********

    リターンコード

    HTTP ステータスコード

    コード

    メッセージ

    200

    Success

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

    400

    MissingParameter

    パラメーターを空にすることはできません。

    InvalidParameter

    無効なパラメーター。

    403

    Forbidden.RAMUserAccessDenied

    RAM ユーザーに AliyunAntCloudAuthFullAccess 権限を付与する必要があります。詳細については、「RAM ユーザーにサービスへのアクセスを承認する」をご参照ください。

    Forbidden.AccountAccessDenied

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

    Throttling.Api

    スロットリングにより API リクエストがブロックされています。

    500

    InternalError

    内部システムエラー。トラブルシューティングのためにエンジニアにフィードバックを提供してください。