すべてのプロダクト
Search

このプロダクト

    ID Verification:初期化

    ドキュメントセンター

    ID Verification:初期化

    最終更新日:Feb 01, 2026

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

    認証リクエストの開始

    • API： Initialize

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

    • 説明： 認証プロセスを開始する前に、この操作を呼び出して transactionId を取得します。transactionId は、認証リクエストに関連するすべての操作を紐付けます。

    • この 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 操作のデバッグと統合」をご参照ください。OpenAPI Explorer での API 呼び出し方法や、SDK およびサンプルコードの取得方法について記載されています。

    OpenAPI Explorer の OpenAPI Explorer では、この操作をデバッグ実行でき、 SDK コード例を生成できます。

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

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

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

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

      説明

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

    • 画像品質に関する推奨事項：

      • 画像内の顔は完全で、鮮明かつ遮蔽されていない必要があります。被写体はカメラに向かって正面を向いている必要があります。フロントカメラで撮影した顔画像の使用を推奨します。

      • 顔は画像領域の 60 ％以上を占める必要があります。顔が小さいと、検出精度が低下する可能性があります。

      • 画像内に複数の顔が存在する場合、アルゴリズムはデフォルトで最も大きな顔を切り出します。複数の顔が含まれる画像の使用は避けてください。

    リクエストパラメーター

    名前

    タイプ

    必須

    説明

    例

    ProductCode

    String

    はい

    使用するプロダクトプランです。有効な値は FACE_VERIFY のみです。

    FACE_VERIFY

    MerchantBizId

    String

    はい

    お客様が定義する一意のビジネス識別子です。問題の追跡およびトラブルシューティングに役立ちます。最大 32 文字の英数字を使用できます。一意性を確保してください。

    説明

    Alibaba Cloud サーバーはこのフィールドの一意性を検証しません。追跡性を高めるため、一意性を厳密に保証することを強く推奨します。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    はい

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

    重要

    • 戻り値を変更せず、そのまま渡してください。

    • サーバーサイドでは、このパラメーターを使用してモバイルまたは PC のランタイム環境を識別し、異なる認証 URL を送信します。関数の説明に従い、実際のランタイム環境からこのパラメーターを取得してください。

    		 
    {
  "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"
}

    MerchantUserId

    String

    はい

    特定のユーザーを識別するためのカスタムユーザー ID またはその他の識別子（例：携帯電話番号やメールアドレス）です。この値は事前にハッシュ化するなど、マスキング処理を施すことを強く推奨します。

    123456789

    ReturnUrl

    String

    いいえ

    ビジネスページでプロセスを完了した後、ユーザーがリダイレクトされる URL です。

    重要

    このパラメーターは、iframe を使用してページを埋め込む場合にのみ省略可能です。

    https://www.alibabacloud.com

    SceneCode

    String

    いいえ

    カスタム認証シナリオ ID です。コンソールでこの ID を入力することで、関連レコードを照会できます。最大 10 文字の英数字またはアンダースコア (_) を使用できます。

    1234567890

    FacePictureBase64

    String

    いいえ

    Base64 エンコードされた写真です。

    顔写真を FacePictureBase64 パラメーターで渡す場合は、以下の要件を満たしてください。

    • 最近撮影した写真を使用してください。顔は完全で、鮮明かつ遮蔽されておらず、自然な表情で、カメラに向かって正面を向いており、角度のずれが大きくない必要があります。

    • 写真は鮮明で、露出が正常である必要があります。暗すぎたり、明るすぎたり、ハレーションが発生している顔は避けてください。

    • 解像度は 640 × 480 ピクセルから 1920 × 1080 ピクセル（高さ × 幅）の範囲内であり、高さが幅より大きい必要があります。

      短辺を 720 ピクセルにスケーリングし、圧縮率を 0.9 以上にしてください。

    • ファイルサイズは 1 MB 未満である必要があります。

    • 写真は時計回りに 90°、180°、または 270° 回転させることができます。

    • 写真には顔が 1 つだけ含まれている必要があります。

    /9j/4AAQSkZJRgABAQAASASBC****

    FacePictureUrl

    String

    いいえ

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

    説明

    プロダクトプランが FACE_VERIFY の場合、FacePictureBase64 または FacePictureUrl のいずれか一方を渡してください。

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

    LanguageConfig

    String

    いいえ

    カスタム言語構成です。追加したい言語構成を構成テンプレートに基づいて JSON 文字列に変換し、このパラメーターを指定してカスタム言語構成を追加します。詳細については、「国際化言語およびカスタムテキストサポート」をご参照ください。

    		 

    {
  "languageContent": {****},
  "ocrResultContent": {****},
  "supportedLanguage": [****],
  "titleTranslate": {****},
}

    SecurityLevel

    String

    いいえ

    検証フローのセキュリティレベルを表すモードです。有効な値は以下のとおりです。

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

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

      説明

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

      • 開発およびテスト中、テストデバイスの環境特性により Device Guard が脅威と判断し、検証が失敗する（サブコード 206）場合があります。テスト効率を向上させるため、テストフェーズでは「01 標準モード」に設定し、本番環境への移行時に「02 セーフモード」に切り替えて検証セキュリティを強化してください。

    02

    StyleConfig

    String

    いいえ

    カスタム UI 構成です。追加したい UI 構成を構成テンプレートに基づいて JSON 文字列に変換し、このパラメーターを指定してカスタム UI 構成を追加します。詳細については、「IDV UI スタイルのカスタマイズ」をご参照ください。

    		 

    {
  "guidepage:": {****}, 
  "ocrPage": {****},
  "ocrResultPage": [****],
  "facePage": {****},
}

    Model

    String

    いいえ

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

    • LIVENESS： 瞬きによる生体検知（デフォルト）。

    • PHOTINUS_LIVENESS： 瞬きによる生体検知および色ベースの生体検知（PC ではサポートされていません）。

    • SILENT： パッシブ生体検知。この機能は現在、Web SDK（モバイル / PC）統合でのみサポートされています。

    説明

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

    PHOTINUS_LIVENESS

    DocVideo

    String

    いいえ

    検証動画を保存するかどうかを指定します。

    • N： いいえ（デフォルト）。

    • Y： 検証中にユーザーの顔スキャンプロセスの動画（1 ～ 2 秒の動画ファイル）を収集し、クエリ API 操作を通じて返却します。

    説明

    動画ファイルはサイズが大きいため、ネットワークが不安定な場合、重要な検証画像の転送を優先するためにシステムが動画を破棄する可能性があります。

    N

    ShowGuidePage

    String

    いいえ

    ガイドページを表示するかどうか：

    説明

    このスイッチは PC ではサポートされていません。

    • 1： 表示（デフォルト）

    • 0： 表示しない

    1

    ProcedurePriority

    String

    いいえ

    モバイル H5 認証中に互換性の問題が発生した場合に、フォールバックソリューションを許可するかどうかを指定します。

    • url（デフォルト）： フォールバックをサポートします。認証 URL がページ上に表示され、ユーザーは URL をコピーするかブラウザを切り替えて認証を継続できます。

    • keep： フォールバックをサポートしません。エラー理由を直接返して認証フローを終了します。

    説明

    • このスイッチは PC ではサポートされていません。

    • アプリ内に埋め込まれた Web ページ上で認証を行うアプリケーションシナリオの場合、URL フォールバックを許可しないよう、このパラメーターを keep に設定してください。

    url

    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

    いいえ

    リプレイ防止および改ざん防止のためのセキュリティトークンです。お客様が生成します。

    この値を設定すると、CallbackUrl コールバックに CallbackToken フィールドが含まれます。

    NMjvQanQgplBSaEI0sL********

    AppQualityCheck

    String

    いいえ

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

    重要

    この機能は Web SDK ではサポートされていません。

    • Y： 有効（デフォルト）

    • N： 無効

    Y

    戻りデータ

    名前

    タイプ

    説明

    例

    HTTP ステータスコード

    Integer

    HTTP ステータスコードです。

    200

    HTTP 本文

    RequestId

    String

    リクエスト ID です。

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

    Code

    String

    リターンコードです。

    Success

    Message

    String

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

    Success

    Result.TransactionId

    String

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

    重要

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

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

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

    hksb7ba1b28130d24e015d6********

    Result.TransactionUrl

    String

    Web 認証 URL です。認証後、ユーザーは ReturnUrl リクエストパラメーターに基づいてリダイレクトされます。

    重要

    • 統合時には、TransactionUrl を変更しないでください。変更すると検証が失敗する可能性があります。

    • 安全かつ効果的な検証プロセスを確保するため、TransactionUrl は 1 回のみ使用可能です。URL を再利用すると、検証が失敗します。

    • TransactionId または TransactionUrl を取得後、30 分以内に検証を完了する必要があります。この期間を過ぎると、ID または URL は有効期限切れとなります。

    https://www.alibabacloud.com/index.html?clientcfg=****

    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

    内部システムエラーが発生しました。技術サポートまでご連絡ください。