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

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.cn-hongkong.aliyuncs.com

    • 同一リージョン内の内部エンドポイント: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

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

説明

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

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

リクエストパラメーター

名前

タイプ

必須

説明

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 SDK の統合」をご参照ください。

説明

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

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

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 Webhook に含まれます。

NMjvQanQgplBSaEI0sL86WnQplB

AppQualityCheck

String

いいえ

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

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

  • N: いいえ

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

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

N

応答パラメーター

名前

タイプ

説明

HTTP ステータスコード

Integer

HTTP ステータスコード。

200

HTTP Body

RequestId

String

リクエスト ID。

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

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

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

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

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