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

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

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

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

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

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

timestamp

string

Yes

タイムスタンプ

通常のレスポンス

// Picture binary data stream

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

コード
メッセージ
説明

600

Sync Failed

写真取得のリモートプロシージャコールに失敗しました

30001

Param Invalid

写真IDが見つかりません

30001

Param Invalid

写真タイプが不正です

前へ2.7 レコードの API次へ2.9 部署の API

最終更新