2.8 認証用顔写真の API

2.8.1 顔の数の検知 (/api/v1/recognition/check)

概要

認証用顔写真内の顔の数を特定します。

リクエストアドレスの例

https://link.japancv.co.jp/api/v1/recognition/check

リクエスト方法

POST: form-data

リクエストパラメーター

パラメーター名	型	必須	説明
face_avatar	file	Yes	認証用顔写真

認証パラメーター

パラメーター名	型	必須	説明
app_key	string	Yes	Appキー
sign	string	Yes	シグネチャ。1.3.1 シグネチャ（sign）の計算の項を参照してください
timestamp	string	Yes	タイムスタンプ

通常のレスポンス

{
 "code": 200,
 "message": "OK",
 "data": 4
}

レスポンスのフィールド

パラメーター名	型	説明
code	int	リターンコード
message	string	リターンメッセージ
desc	string	不正なリターンの説明
data	int	顔の数

エラーレスポンスのフィールド

コード	メッセージ	説明
30001	Param Invalid	認証用顔写真のタイプが不正です
30003	No Face Detected In The Image	顔が検出されませんでした。

2.8.2 認証用顔写真品質の検出 (/api/v3/recognition/quality)

概要

選定した品質チェックレベルで、認証用顔写真の品質を検出します。 写真に複数の顔がある場合、最大の顔の情報のみ表示されます。

リクエストアドレスの例

https://link.japancv.co.jp/api/v3/recognition/quality

リクエスト方法

POST: form-data

リクエストパラメーター

パラメーター名	型	必須	説明
face_avatar	file	Yes	認証用顔写真
qa_level	int	No	品質チェックレベル。1：低、2：高、3：厳格。既定値は3です。

品質チェックレベル：

• 低：写真のサイズ、ファイルのフォーマット、顔の数のみに基づく簡単な判断です。低品質の顔認証運用に適しています。

• 高：写真のサイズ、ファイルのフォーマット、顔の数、顔のサイズ、顔の角度、明るさ、ぼやけさ、口の開き状況、目、鼻、口の遮蔽などの多要素に基づく包括的な判断です。高品質の顔認識が必要な運用に適しています。

• 厳格：パスポートの要件を参照し、写真のサイズ、ファイルのフォーマット、顔の数、顔のサイズ、顔の角度、明るさ、ぼやけさ、口の開き状況、目、眉毛、顔の輪郭、鼻、口の遮蔽などの多要素に基づく包括的な判断です。厳格な顔認証が必要な運用に適しています。

認証パラメーター

パラメーター名	型	必須	説明
app_key	string	Yes	Appキー
sign	string	Yes	シグネチャ。1.3.1 シグネチャ（sign）の計算の項を参照してください
timestamp	string	Yes	タイムスタンプ

通常のレスポンス（qa_level='1'）

{
    "code": 200,
    "message": "OK",
    "data": {
        "qa_code": 0,
        "qa_desc": "Pass",
        "qa_msg": "Pass"
    }
}

通常のレスポンス（qa_level='2'）

{
    "code": 200,
    "message": "OK",
    "data": {
        "face": {
            "pose": { 
                "yaw": -6.984859, 
                "pitch": 14.09827, 
                "roll": -2.4992712 
            },
            "distance2center": 0.8623486, 
            "size": 0.39172968,  
            "brightness": 0.29538798, 
            "sharpness": 1.0, 
            "missing": 1.0,  
            "occlusion_total":0.9,
            "mouth_open": 0.9553734 
        },
        "qa_code": 0,
        "qa_desc": "Pass",
        "qa_msg": "Pass"
    }
}

通常のレスポンス（qa_level='3'）

{
    "code": 200,
    "message": "OK",
    "data": {
        "face": {
            "pose": { 
                "yaw": -6.984859, 
                "pitch": 14.09827, 
                "roll": -2.4992712 
            },
            "occlusion": { 
                "eye": 1.0, 
                "nose": 1.0, 
                "mouth": 1.0, 
                "eyebrow": 1.0, 
                "face_line": 0.9
            },
            "distance2center": 0.8623486, 
            "size": 0.39172968,  
            "brightness": 0.29538798, 
            "sharpness": 1.0, 
            "missing": 1.0,  
            "mouth_open": 0.9553734 
        },
        "qa_code": 0,
        "qa_desc": "Pass",
        "qa_msg": "Pass"
    }
}

レスポンスのフィールド

パラメーター名	型	説明
qa_code	int	リターンコード
qa_msg	string	リターンメッセージ
qa_desc	string	リターンの説明
face	Object	顔の品質情報（qa_codeは0「通過」の場合のみ、表示されます）

face項目の説明（qa_level='2'）

パラメーター名	型	値域	説明
pose/yaw	float	[-90,90]	顔が上下を軸にした回転角度 頭が左寄りのほど、値は大きくなります
pose/pitch	float	[-90,90]	顔が左右を軸にした回転角度 頭が下げたほど、値は大きくなります
pose/roll	float	[-90,90]	顔が前後を軸にした回転角度 頭が反時計回りのほど、値は大きくなります
occlusion_total	float	[0,1]	目が遮蔽された度合い 目の遮蔽が少ないほど、値は大きくなります
distance2center	float	[0,1]	顔の中心と写真の中心との位置偏差 2つの中心の距離が近いほど、値は大きくなります
size	float	[0,1]	写真全体に対する顔枠面積の比率 顔枠の面積が大きいほど、値は大きくなります
brightness	float	[-1,1]	顔枠の平均明るさ 明るいほど、値は大きくなります
sharpness	float	[-1,1]	MAGICアルゴリズムで計算したシャープネス（鋭さ） 鋭いほど、値は大きくなります
missing	float	[0,1]	ランディングポイントが写真の中に含めない度合い 含まれていないランディングポイントが少ないほど、値は大きくなります
occlusion_total	float	[0,1]	目・口・鼻が遮蔽された度合い 目・口・鼻の遮蔽が少ないほど、値は大きくなります
mouth_open	float	[0,1]	口が閉じている度合い 口が閉まるほど、値は大きくなります

face項目の説明（qa_level='3'）

パラメーター名	型	値域	説明
pose/yaw	float	[-90,90]	顔が上下を軸にした回転角度 頭が左寄りのほど、値は大きくなります
pose/pitch	float	[-90,90]	顔が左右を軸にした回転角度 頭が下げたほど、値は大きくなります
pose/roll	float	[-90,90]	顔が前後を軸にした回転角度 頭が反時計回りのほど、値は大きくなります
occlusion/eye	float	[0,1]	目が遮蔽された度合い 目の遮蔽が少ないほど、値は大きくなります
occlusion/nose	float	[0,1]	鼻が遮蔽された度合い 鼻の遮蔽が少ないほど、値は大きくなります
occlusion/mouth	float	[0,1]	口が遮蔽された度合い 口の遮蔽が少ないほど、値は大きくなります
occlusion/eyebrow	float	[0,1]	眉毛が遮蔽された度合い 眉毛の遮蔽が少ないほど、値は大きくなります
occlusion/face_line	float	[0,1]	顔の輪郭が遮蔽された度合い 顔の輪郭が遮蔽が少ないほど、値は大きくなります
distance2center	float	[0,1]	顔の中心と写真の中心との位置偏差 2つの中心の距離が近いほど、値は大きくなります
size	float	[0,1]	写真全体に対する顔枠面積の比率 顔枠の面積が大きいほど、値は大きくなります
brightness	float	[-1,1]	顔枠の平均明るさ 明るいほど、値は大きくなります
sharpness	float	[-1,1]	MAGICアルゴリズムで計算したシャープネス（鋭さ） 鋭いほど、値は大きくなります
missing	float	[0,1]	ランディングポイントが写真の中に含めない度合い 含まれていないランディングポイントが少ないほど、値は大きくなります
mouth_open	float	[0,1]	口が閉じている度合い 口が閉まるほど、値は大きくなります

qa_code の説明（qa_level='1'）

リターンコード	リターンメッセージ	リターンの説明
0	PASS	通過
100	Internal error	内部エラー
101	Face count is over the max	顔の数が制限値を超えています
102	No face detected	顔を検知できませんでした
103	Read image file failed	顔写真の読み取りに失敗しました
104	Image file error format	顔写真のファイルタイプが不正です
105	Image too big	顔写真のサイズが大きすぎます

qa_code の説明（qa_level='2'）

リターンコード	リターンメッセージ	リターンの説明
0	PASS	通過
100	Internal error	内部エラー
101	Face count is over the max	顔の数が制限値を超えています
102	No face detected	顔を検知できませんでした
103	Read image file failed	顔写真の読み取りに失敗しました
104	Image file error format	顔写真のファイルタイプが不正です
105	Image too big	顔写真のサイズが大きすぎます
10201	Image pixels is too small	顔写真のサイズが小さくて認識できません。300x400ピクセル以上の顔写真データを使用してください
10301	The alignment score is substandard	検知スコアが低すぎます
1030201	Face frame pixels too small	画像中の顔部分が小さくて認識できません。少なくとも150x150ピクセル以上の顔画像が必要です
1030301	The face pose pitch is substandard	ピッチ角が大きすぎます
1030302	The face pose yaw is substandard	転向角が大きすぎます
1030303	The face pose roll is substandard	ロール角が大きすぎます
10401	Face distance to center is substandard	対面距離が基準を満たしていません
10402	Face size is substandard	顔サイズ比が小さすぎます（顔の長方形の領域／ 画像領域）
10403	Face covered is substandard	顔が遮られすぎています
10404	Brightness is substandard	明るさが基準を満たしていません
10405	Sharpness is substandard	写真がぼやけています
10406	Mouth opened is substandard	口が開き過ぎています
10407	Face missing is substandard	欠けた顔の画像が多すぎます

qa_code の説明（qa_level='3'）

リターンコード	リターンメッセージ	リターンの説明
0	PASS	通過
100	Internal error	内部エラー
102	No face detected	顔を検知できませんでした
103	Read image file failed	顔写真の読み取りに失敗しました
104	Image file error format	顔写真のファイルタイプが不正です
105	Image too big	顔写真のサイズが大きすぎます
106	Image is black and white	白黒の顔写真は利用できません。カラー写真を使用してください
10201	Image pixels is too small	顔写真のサイズが小さくて認識できません。300x400ピクセル以上の顔写真データを使用してください
10301	The alignment score is substandard	検知スコアが低すぎます
1030201	Face frame pixels too small	画像中の顔部分が小さくて認識できません。少なくとも150x150ピクセル以上の顔画像が必要です
1030301	The face pose pitch is substandard	ピッチ角が大きすぎます
1030302	The face pose yaw is substandard	転向角が大きすぎます
1030303	The face pose roll is substandard	ロール角が大きすぎます
10401	Face distance to center is substandard	対面距離が基準を満たしていません
10402	Face size is substandard	顔サイズ比が小さすぎます（顔の長方形の領域／ 画像領域）
10403	Face covered is substandard	顔が遮られすぎています
104031	Eyes covered is substandard	目が遮られすぎています
104032	Nose covered is substandard	鼻が遮られすぎています
104033	Mouth covered is substandard	口が遮られすぎています
104034	Eyebrow covered is substandard	眉毛が遮られすぎています
104035	Face contour covered is substandard	顔枠が遮られすぎています
10404	Brightness is substandard	明るさが基準を満たしていません
10405	Sharpness is substandard	写真がぼやけています
10406	Mouth opened is substandard	口が開き過ぎています
10407	Face missing is substandard	欠けた顔の画像が多すぎます

エラーレスポンスのフィールド

コード	メッセージ	説明
30001	Param Invalid	qa_levelが1,2,3のみをサポートします
50002	Internal Server Error	シリアル化エラー

2.8.3 認証用顔写真品質の検出 (/api/v2/recognition/quality)

概要

「厳格」の品質チェックレベルで、認証用顔写真の品質を検出します。 写真に複数の顔がある場合、最大の顔の情報のみ表示されます。

品質チェックレベルを指定したい場合、V3のAPIをご参照ください。

リクエストアドレスの例

https://link.japancv.co.jp/api/v2/recognition/quality

リクエスト方法

POST: form-data

リクエストパラメーター

パラメーター名	型	必須	説明
face_avatar	file	Yes	認証用顔写真

認証パラメーター

パラメーター名	型	必須	説明
app_key	string	Yes	Appキー
sign	string	Yes	シグネチャ。1.3.1 シグネチャ（sign）の計算の項を参照してください
timestamp	string	Yes	タイムスタンプ

通常のレスポンス

{
    "code": 200,
    "message": "OK",
    "data": {
        "face": {
            "pose": { 
                "yaw": -6.984859, 
                "pitch": 14.09827, 
                "roll": -2.4992712 
            },
            "occlusion": { 
                "eye": 1.0, 
                "nose": 1.0, 
                "mouth": 1.0, 
                "eyebrow": 1.0, 
                "face_line": 0.9
            },
            "distance2center": 0.8623486, 
            "size": 0.39172968,  
            "brightness": 0.29538798, 
            "sharpness": 1.0, 
            "missing": 1.0,  
            "mouth_open": 0.9553734 
        },
        "qa_code": 0,
        "qa_desc": "Pass",
        "qa_msg": "Pass"
    }
}

レスポンスのフィールド

パラメーター名	型	説明
qa_code	int	リターンコード
qa_msg	string	リターンメッセージ
qa_desc	string	リターンの説明
face	Object	顔の品質情報（qa_codeは0「通過」の場合のみ、表示されます）

face項目の説明

パラメーター名	型	値域	説明
pose/yaw	float	[-90,90]	顔が上下を軸にした回転角度 頭が左寄りのほど、値は大きくなります
pose/pitch	float	[-90,90]	顔が左右を軸にした回転角度 頭が下げたほど、値は大きくなります
pose/roll	float	[-90,90]	顔が前後を軸にした回転角度 頭が反時計回りのほど、値は大きくなります
occlusion/eye	float	[0,1]	目が遮蔽された度合い 目の遮蔽が少ないほど、値は大きくなります
occlusion/nose	float	[0,1]	鼻が遮蔽された度合い 鼻の遮蔽が少ないほど、値は大きくなります
occlusion/mouth	float	[0,1]	口が遮蔽された度合い 口の遮蔽が少ないほど、値は大きくなります
occlusion/eyebrow	float	[0,1]	眉毛が遮蔽された度合い 眉毛の遮蔽が少ないほど、値は大きくなります
occlusion/face_line	float	[0,1]	顔の輪郭が遮蔽された度合い 顔の輪郭が遮蔽が少ないほど、値は大きくなります
distance2center	float	[0,1]	顔の中心と写真の中心との位置偏差 2つの中心の距離が近いほど、値は大きくなります
size	float	[0,1]	写真全体に対する顔枠面積の比率 顔枠の面積が大きいほど、値は大きくなります
brightness	float	[-1,1]	顔枠の平均明るさ 明るいほど、値は大きくなります
sharpness	float	[-1,1]	MAGICアルゴリズムで計算したシャープネス（鋭さ） 鋭いほど、値は大きくなります
missing	float	[0,1]	ランディングポイントが写真の中に含めない度合い 含まれていないランディングポイントが少ないほど、値は大きくなります
mouth_open	float	[0,1]	口が閉じている度合い 口が閉まるほど、値は大きくなります

qa_code の説明

リターンコード	リターンメッセージ	リターンの説明
0	PASS	通過
100	Internal error	内部エラー
102	No face detected	顔を検知できませんでした
103	Read image file failed	顔写真の読み取りに失敗しました
104	Image file error format	顔写真のファイルタイプが不正です
105	Image too big	顔写真のサイズが大きすぎます
106	Image is black and white	白黒の顔写真は利用できません。カラー写真を使用してください
10201	Image pixels is too small	顔写真のサイズが小さくて認識できません。300x400ピクセル以上の顔写真データを使用してください
10301	The alignment score is substandard	検知スコアが低すぎます
1030201	Face frame pixels too small	画像中の顔部分が小さくて認識できません。少なくとも150x150ピクセル以上の顔画像が必要です
1030301	The face pose pitch is substandard	ピッチ角が大きすぎます
1030302	The face pose yaw is substandard	転向角が大きすぎます
1030303	The face pose roll is substandard	ロール角が大きすぎます
10401	Face distance to center is substandard	対面距離が基準を満たしていません
10402	Face size is substandard	顔サイズ比が小さすぎます（顔の長方形の領域／ 画像領域）
10403	Face covered is substandard	顔が遮られすぎています
104031	Eyes covered is substandard	目が遮られすぎています
104032	Nose covered is substandard	鼻が遮られすぎています
104033	Mouth covered is substandard	口が遮られすぎています
104034	Eyebrow covered is substandard	眉毛が遮られすぎています
104035	Face contour covered is substandard	顔枠が遮られすぎています
10404	Brightness is substandard	明るさが基準を満たしていません
10405	Sharpness is substandard	写真がぼやけています
10406	Mouth opened is substandard	口が開き過ぎています
10407	Face missing is substandard	欠けた顔の画像が多すぎます

エラーレスポンスのフィールド

コード	メッセージ	説明
50002	Internal Server Error	シリアル化エラー

2.8.4 認証用顔写真品質の検出 (/api/v1/recognition/quality)

概要

認証用顔写真の品質を検出します。

リクエストアドレスの例

https://link.japancv.co.jp/api/v1/recognition/quality

リクエスト方法

POST: form-data

リクエストパラメーター

パラメーター名	型	必須	説明
face_avatar	file	Yes	認証用顔写真

認証パラメーター

パラメーター名	型	必須	説明
app_key	string	Yes	Appキー
sign	string	Yes	シグネチャ。1.3.1 シグネチャ（sign）の計算の項を参照してください
timestamp	string	Yes	タイムスタンプ

通常のレスポンス

{
    "code": 200,
    "message": "OK",
    "data": {
        "qa_code": 1030301,
        "qa_desc": "the face pose pitch score is [22.19]-float",
        "qa_msg": "BAN:the face pose pitch is substandard"
    }
}

レスポンスのフィールド

パラメーター名	型	説明
qa_code	int	リターンコード
qa_msg	string	リターンメッセージ
qa_desc	string	リターンの説明

qa_code の説明

リターンコード	リターンメッセージ	リターンの説明
0	PASS	通過
101	BAN:face count is over the max	顔の数が最大数の制限を超えています
10201	BAN:image size wrong, two small	認証用顔写真が小さすぎます
10301	BAN:the alignment score is substandard	検知スコアが低すぎます
1030201	BAN:the face rect's pixels is too low	顔フレームのピクセルが少なすぎます
1030301	BAN:the face pose pitch is substandard	ピッチ角が大きすぎます
1030302	BAN:the face pose yaw is substandard	転向角が大きすぎます
1030303	BAN:the face pose roll is substandard	ロール角が大きすぎます
10401	BAN:the face quality{distance to center} is substandard	対面距離が基準を満たしていません
10402	BAN:the face quality{face size} is substandard	顔サイズ比が小さすぎます（顔の長方形の領域／ 画像領域）
10403	BAN:the face quality{face cover} is substandard	顔が遮られすぎています
10404	BAN:the face quality{brightness} is substandard	明るさが基準を満たしていません
10405	BAN:the face quality{sharpness} is substandard	明度が基準を満たしていません（写真がぼやけています）
10406	BAN:the face quality{mouth opened} is substandard	口が開き過ぎています
10407	BAN:the face quality{face missing} is substandard	欠けた顔が多すぎます

エラーレスポンスのフィールド

コード	メッセージ	説明
30001	Param Invalid	無効なパラメーターです
30001	Param Invalid	写真が大きすぎます
30005	Avatar File Illegal	ファイルのサイズが大きすぎます
30005	Avatar File Illegal	処理中にエラーが発生しました
30006	Face Number Invalid	無効な顔です
50002	Internal Server Error	シリアル化エラー

2.8.5 顔検索 (/api/v1/image/search)

当APIをご利用いただくためには、「SenseLink Cloud Professional Annual Subscription」と「SenseLink Cloud ID Pack Annual Subscription」、両方のご契約が必要となります。ご了承ください。

概要

顔写真を指定し、現在のテナントに登録されている顔情報から検索し、類似した上位Kの結果を返します。認識結果は、認証スコアの高から低の順に返されます。 認証スコアが同じ場合、登録写真の登録時間の新から旧の順に返されます。

最も正確な検索結果を取得する為に、以下の事項をご確認ください。

• JPG、PNG、BMP、TIFF、GIF（最初の1フレーム）のフォーマットを使用してください。

• 写真のサイズは最大8MBですが、事前に画像を200KB未満にトリミングまたは圧縮することを強くお勧めします。

• 検出可能な最小の顔フレームサイズは、32x32ピクセルです。

• 写真の画質が高いほど、精度が高くなります。 高品質で、単一の顔、正面、鮮明で、顔のサイズが200x200ピクセル以上の写真の使用を検討してください。

• 一枚の写真に複数の顔がある場合、最大の顔のみが検索されます。

リクエストアドレスの例

https://link.japancv.co.jp/api/v1/image/search

リクエスト方法

POST　application/json

リクエストパラメーター

パラメーター名	型	必須	説明
image_base64	string	Yes	base64で暗号化後の写真データ
top_k	int	No	最も類似した顔の数を設定します デフォルトは1で、最大10です
threshold	float	No	認証スコアのしきい値 デフォルトは0.9で、範囲は0～1です

認証パラメーター

パラメーター名	型	必須	説明
app_key	string	Yes	Appキー
sign	string	Yes	シグネチャ。1.3.1 シグネチャ（sign）の計算の項を参照してください
timestamp	string	Yes	タイムスタンプ

通常のレスポンス

{
 "code": 200,
 "message": "OK",
  "data": [
    {
      "type": 5,
      "score": 0.9747194,
      "user_id": 24089,
      "image_id": "60869eea895750000142d2bd"
    },
    {
      "type": 1,
      "score": 0.9747194,
      "user_id": 24087,
      "image_id": "60869e491ddb2800017e8c09"
    }
  ]
}

レスポンスのフィールド

パラメーター名	型	説明
code	int	リターンコード
message	string	リターンメッセージ
data	array	顔写真の情報

data フィールドの説明

パラメーター名	型	説明
user_id	int	登録者ID
image_id	string	登録者の認証用顔写真
score	float	認証スコア
type	int	登録者の識別タイプ。 1：従業員、2：ビジター、5：拒否リスト

エラーレスポンスのフィールド

コード	メッセージ	説明
30001	Param Invalid	認証スコアのしきい値が不正
30001	Param Invalid	top_kが設定範囲外
30001	Param Invalid	認証スコアのしきい値は空にはできません
30001	Param Invalid	top_kは空にはできません
30001	Param Invalid	顔写真が大きすぎます
30001	Param Invalid	顔写真は空にはできません
30007	Server Face Recognition Not Supported	サーバー認証プランを使用しているテナントのみ使用可能

2.8.6 顔写真の取得（/v1/image/{type}/{image_id}）

概要

登録者のタイプと写真のIDを指定し、該当する写真（圧縮後）が返されます。

リクエストアドレスの例

https://link.japancv.co.jp/api/v1/image/{type}/{image_id}

リクエスト方法

GET

リクエストパラメーター

パラメーター名	型	必須	説明
type	int	Yes	写真のタイプ 1: 認証用顔写真 2: 認証時にデバイスが撮影した写真、認証時にデバイスが撮影したパックグラウンド写真、認証時にデバイスが撮影したサーマル画像を含む認証時の写真 3: アラート写真
image_id	string	Yes	写真のID タイプ1の写真IDは下記APIから取得できます - /api/v1/user - /api/v1/guest - /api/v2/user/update/{id} - /api/v1/guest/update/{id} - /api/v1/user/list - /api/v2/black/update - /api/v2/black タイプ2の写真IDは下記APIから取得できます - /api/v5/record/list タイプ3の写真IDは下記APIから取得できます - /api/v2/device/alarm/list

認証パラメーター

パラメーター名	型	必須	説明
app_key	string	Yes	Appキー
sign	string	Yes	シグネチャ。1.3.1 シグネチャ（sign）の計算の項を参照してください
timestamp	string	Yes	タイムスタンプ

通常のレスポンス

// Picture binary data stream

エラーレスポンスのフィールド

コード	メッセージ	説明
600	Sync Failed	写真取得のリモートプロシージャコールに失敗しました
30001	Param Invalid	写真IDが見つかりません
30001	Param Invalid	写真タイプが不正です