オンライン顔照合 API

バックエンドから 2 枚の顔画像を比較し、文書化された dist、sim、same_person シグナルを取得します。結果の使い方はアプリケーション側で決定します。ブラウザーでライブ撮影を行うフローについては、オンライン顔照合を参照してください。

FACEIO Console を開く

FACEIO Console に接続してアプリケーションを作成し、API を管理し、登録、認証、Facial ID イベント用の webhook を設定します。

検証をフローに組み込む方法

アーキテクチャとユーザー操作モデルに合った統合方法を選択します。

FACEIO では、システム内で照合を行う場所に応じて 2 つの方法を提供します。ブラウザーフローでは fio.jsでカメラ操作とライブ撮影を行います。REST API は、比較する 2 枚の顔画像をすでに持つバックエンドサービス向けです。本人確認書類の撮影とライブセルフィーを組み合わせたブラウザーポップアップについては、FACEIO ID Matchを参照してください。方式の違いについては、オンライン顔照合フローで確認できます。

ブラウザーベース SDK

ユーザーがその場で操作するインタラクションポイントで検証する場合に適しています。

fio.js カメラ UI とライブ撮影を処理
KYC オンボーディングとアカウント復旧に適しています
バックエンドがペイロードを検証して判断

直接 REST API

画像がすでにサーバーにあるバックエンド専用フローに適しています。

直接 /faceverify エンドポイント呼び出し
バックエンドでの画像比較と ID 確認に便利
ブラウザーのライブセッションは不要

API 入力と検証シグナル

faceverify API は、API キーと 2 枚の画像を含む POST リクエストを受け付けます。画像は Base64 data URI または公開 URL で指定できます。各画像には 1 人の顔だけを含めてください。複数の顔がある場合は、リクエスト前に対象の顔を抽出します。

リクエスト入力

パラメーター	説明
`key`	アプリケーションの REST API キー。この値はバックエンドからのみ送信してください。クライアント側のコードに公開しないでください。
`src`	Base64 data URI または公開 URL で指定するソース画像。通常は ID 書類の写真または以前に検証済みのセルフィーです。
`target`	ソースと比較する対象画像。Base64 data URI または公開 URL で指定します。

レスポンス出力

フィールド	型	説明
`status`	Integer	HTTP ステータスコード。 `200` リクエストが正常に処理されたことを示します。
`same_person`	Boolean	`true` 2 枚の画像が一致する場合は `false` 一致しない場合は
`dist`	Float	0 から 1 の距離指標。値が高いほど一致が強いことを示します。
`sim`	Float	2 つの顔特徴ベクトル間のコサイン類似度スコア。

実装のヒント: 重要なフローでは、dist と sim を判定ロジックに組み込み、二値の same_person だけに依存しないでください。一致しきい値を文書化したポリシーに合わせ、セキュリティのベストプラクティスを確認してください。

実装パターン

1. ブラウザー撮影による Web オンボーディング (KYC)

KYC 型フローでは、登録時にブラウザーで顔をライブ撮影します。バックエンドは、その撮影画像と前段の書類スキャンから得た参照画像を指定し、faceverify を呼び出して 2 枚を比較します。レスポンスは、顧客が管理するオンボーディング、再試行、手動確認ポリシーの技術的な入力の一つです。書類を認証したり、KYC や AML の確認を完了したりするものではありません。

                         backend_verify.py 
                      

                        # Python - backend verification call
import requests, base64

def encode_image(path):
    with open(path, 'rb') as f:
        return 'data:image/jpeg;base64,' + base64.b64encode(f.read()).decode()

payload = {
    'key': 'YOUR_API_KEY',
    'src': encode_image('id_document.jpg'),   # reference
    'target': encode_image('live_selfie.jpg') # live capture
}

result = requests.post('https://api.faceio.net/faceverify', json=payload).json()

# Example Response
# {
#     "status": 200,
#     "same_person": true,
#     "dist": 0.97,
#     "sim": 0.94
# }
                      

2. 信頼度しきい値によるバックエンド判定

バックエンドは文書化されたレスポンス項目を読み取り、用途ごとに定義したしきい値と確認ルールに従ってリクエストを振り分けられます。サンプルのしきい値を普遍的な基準とせず、自社のデータと要件でルールをテストしてください。このパターンは、フィンテックと eKYCの管理策の一部として利用できます。

高信頼

組織が定義してテストした続行ポリシーを適用します。

境界信頼度

信頼度が低い結果は自動拒否せず、手動確認キューに送ります。

低信頼

ポリシーに従い、再試行、別の要素、または確認を求めます。

3. アカウント情報を使わない復旧

ユーザーがアカウントへのアクセスを要求し、復旧ページから新しいセルフィーを送信します。バックエンドは、そのアカウント用に保持している参照画像と比較します。

顔照合結果は復旧シグナルの一つとして扱ってください。アクセスを復旧する前に、バックエンドで必要なアカウント、デバイス、セッション、再試行、サポートの管理策も適用する必要があります。

セキュリティとプライバシーのベストプラクティス

顔照合 API は、比較ごとに機微な顔画像を一時的に処理します。通知、同意、入力検証、アプリケーション側の保持ポリシー、アカウントに関する最終判断はアプリケーション側の責任です。すべての統合で次の実践を使用してください。

API キーを非公開にする
この faceverify エンドポイントはバックエンドからのみ呼び出してください。API キーはリクエストを認証するため、ブラウザーコード、モバイルバンドル、公開リポジトリ、分析データ、ログに含めてはいけません。
必ずバックエンドを経由する
ブラウザーから直接送信された検証リクエストはサーバー側の検証層を迂回するため、信頼できません。
画像の保持を最小限にする
FACEIO は 2 枚の画像をメモリ上で処理し、結果生成後に破棄します。アプリケーションは、ワークフロー、ポリシー、法的根拠で必要な場合にのみ顔画像を保持してください。
監査証跡のために検証結果を記録する
監査証跡が必要な場合、レスポンス受信時にバックエンドで結果、タイムスタンプ、リクエストコンテキスト、関連する内部識別子を記録してください。元画像や API キーはログに記録しないでください。
必要な場合は通知を行い、同意を取得する
オンボーディングまたは復旧フローでは、顔照合を使う理由、処理するデータ、削除や代替アクセスを申請する方法を説明してください。詳しくは、プライバシーのベストプラクティスとトラストセンターを確認してください。

まとめ

FACEIO 顔照合 API は、バックエンドから 2 枚の顔画像を比較するための明確な方法を提供します。画像と判定しきい値を指定すると API が照合シグナルを返し、最終判断はアプリケーションロジックが行います。ライブネスチェック付きのブラウザー撮影フローには、オンライン顔照合を使用してください。書類スキャンとセルフィー照合を 1 つのウィジェットで行う場合は、 ID Matchを使用します。次のステップとして、開発者ガイド、FACEVERIFY endpoint、セキュリティのベストプラクティスを確認してください。

顔照合 API を接続

FACEIO アプリを作成し、REST API キーをバックエンドに保持して、公式エンドポイントリファレンスで本人確認フローのソース画像と対象画像を比較します。

FACEIO Console を開く REST API リファレンス

バックエンド専用 API キー

一時的な処理

ポリシーに基づく統合