顔画像をセルフィーと照合する

POST

/v1/verification-sessions/{id}/face-match

curl --request POST \
  --url https://api.trust.supa.ai/v1/verification-sessions/example/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "imageBase64": "example" }'

• production
• staging

送った顔画像を、そのセッションで利用者が本人確認のときに撮ったセルフィーと比べ、類似度(similarity)と同一人物かどうか(isSamePerson)を返す。同一人物の判定はテナントの顔照合しきい値(管理画面の設定)で決まる。利用者がセルフィーを終える前は 409。送った画像は保存しない。照合は記録される。画像は個人情報なので、送る側でもログに出さない

Authorizations

• bearer

Parameters

Path Parameters

id

required

string

Request Body^required

Media typeapplication/json

object

imageBase64

required

照合したい顔画像(JPEG か PNG)を base64(RFC 4648 の標準アルファベット・末尾の = あり)にした文字列。data URL(data:image/jpeg;base64,…)の形でもよい。上限 7,000,000 文字(元の画像で約 5MB)。個人情報 — ログに出さない

>= 1 characters

<= 7000000 characters

Example^generated

{
  "imageBase64": "example"
}

Responses

200

送った顔画像と、本人確認で撮ったセルフィーの照合結果。送った画像は保存しない。照合は記録される

Media typeapplication/json

object

similarity

required

<= 1

isSamePerson

required

同一人物と判定したか。similarity がテナントの顔照合しきい値(管理画面の設定)以上なら true

boolean

status

required

Success = 両方の顔を比べられた / no_face_in_selfie = 本人確認時のセルフィーに顔が見つからない / no_face_in_image = 送った画像に顔が見つからない。success 以外は similarity 0・isSamePerson false

string

Allowed values: success no_face_in_selfie no_face_in_image

Example

{
  "similarity": 0.97,
  "status": "success"
}

400

送った画像が顔照合に使えない。reason を見て画像を直す

Media typeapplication/json

object

_tag

required

string

Allowed values: FaceMatchImageInvalid

reason

required

Invalid_image_format = JPEG / PNG として読めない(base64 の中身を確かめる) / image_too_large = 画像が大きすぎる(縮小して送る)

string

Allowed values: invalid_image_format image_too_large

Example

{
  "_tag": "FaceMatchImageInvalid",
  "reason": "invalid_image_format"
}

401

API キーが無い・正しくない・失効している(理由は区別しない)。Authorization: Bearer <API キー> を確かめる

Media typeapplication/json

object

_tag

required

string

Allowed values: Unauthorized

message

required

string

Example

{
  "_tag": "Unauthorized"
}

403

テナントの IP 許可リストに無いアドレスからの呼び出し。API キーは有効。許可リストの設定を確かめる

Media typeapplication/json

object

_tag

required

string

Allowed values: IpNotAllowed

message

required

string

Example

{
  "_tag": "IpNotAllowed"
}

404

セッションが無い。他テナントのセッション・形式が正しくない ID も同じく 404(個人情報を消去済みのセッションは 404 にならない)

Media typeapplication/json

object

_tag

required

string

Allowed values: SessionNotFound

id

required

string

Example

{
  "_tag": "SessionNotFound"
}

409

今の状態では顔照合できない。reason で対処が分かれる(liveness_not_completed = 利用者の手続きを待つ / purged = 二度とできない)

Media typeapplication/json

object

_tag

required

string

Allowed values: FaceMatchNotAllowed

id

required

string

reason

required

Liveness_not_completed = 利用者がまだ顔の確認(セルフィー)を終えていない。終えてからやり直す / purged = 個人情報を消去済みで、セルフィーも消えている。照合はもうできない

string

Allowed values: liveness_not_completed purged

Example

{
  "_tag": "FaceMatchNotAllowed",
  "reason": "liveness_not_completed"
}