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 | 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')
通常のレスポンス(qa_level='2')
通常のレスポンス(qa_level='3')
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
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 | タイムスタンプ |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
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 | タイムスタンプ |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
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 | 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 | タイムスタンプ |
通常のレスポンス
エラーレスポンスのフィールド
コード | メッセージ | 説明 |
---|---|---|
600 | Sync Failed | 写真取得のリモートプロシージャコールに失敗しました |
30001 | Param Invalid | 写真IDが見つかりません |
30001 | Param Invalid | 写真タイプが不正です |
最終更新