1 of 11

APIマニュアル

SenseIDのAPI利用方法について記載されています。

本章では、必要に応じて参考にできるように、JCV顔認証サービスで提供されるすべてのAPIに関する手順について詳細に説明します。APIの説明には、機能の紹介、パラメーター、出力結果、エラーメッセージなどが含まれます。

改訂履歴

1 顔の比較 (ステートレス)

1.1 /identity/image_verification/stateless

インターフェースを介してアップロードされた2つの顔写真を比較して、2つの顔が同一人物のものかどうかを判断します。

写真の規格は、運用マニュアルの3章写真と動画の規格をご参照ください。

リクエストモード

リクエスト URL

http://ip:port/identity/image_verification/stateless

リクエストパラメーター

通常のレスポンス

{
    "code": 1000,
    "verification_score": float,
    "request_id": string
}

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7以上

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

curl -X POST "http://ip:port/identity/image_verification/stateless" \
  -d first_encrypted_image=xxx \
  -d second_encrypted_image=xxx \
  -d auto_rotate=true

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/image_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String firstEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));
        String secondEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_02.jpg")));

        params.add(new BasicNameValuePair("first_encrypted_image", firstEncryptedImage));
        params.add(new BasicNameValuePair("second_encrypted_image", secondEncryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:"+responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

1.2 /identity/multiface_image_omni_verification/stateless

比較対象の顔写真に複数の顔が含まれる場合、2つの写真に含まれる顔の各グループの類似度スコアを返します。

写真の規格は、運用マニュアルの3章写真と動画の規格をご参照ください。

リクエストモード

リクエスト URL

http://ip:port/identity/multiface_image_omni_verification/stateless

リクエストパラメーター

通常のレスポンス

例:

{
    "code": 1000,
    "scores": [ # [[a1b1 顔比較スコア, a1b2 顔比較スコア], [a2b1 顔比較スコア, a2b2 顔比較スコア]]
  "face_rects":{ hash,# 各写真の顔枠
        [
            float,
            float,
            float,
            float
        ]
    ],
    "face_rects": { # face frame in each image
        "first_image_face_rects": [ # [[a1 顔枠の座標], [a2 顔枠の座標]]
            [
                int,
                int,
                int,
                int
            ],
            [
                int,
                int,
                int,
                int
            ]
        ],
        "second_image_face_rects": [ # [[b1 顔枠の座標],[b2 顔枠の座標]]
            [
                int,
                int,
                int,
                int
            ],
            [
                int,
                int,
                int,
                int
            ]
        ]
    },
    "request_id": "2c4156bb47794f66a2ed50d5a87e5ca2"
}

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7以上

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

curl -X POST "http://ip:port/identity/multiface_image_omni_verification/stateless" \
  -d first_encrypted_image=xxx \
  -d second_encrypted_image=xxx \
  -d auto_rotate=true

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/multiface_image_omni_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String firstEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));
        String secondEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_02.jpg")));

        params.add(new BasicNameValuePair("first_encrypted_image", firstEncryptedImage));
        params.add(new BasicNameValuePair("second_encrypted_image", secondEncryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:" +responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

1.3 /identity/liveness_image_verification/stateless

インターフェースを介してアップロードされた顔画像と生体認証データを比較して、画像内の顔が同一人物のものであるかどうかを判断します。

写真の規格は、のをご参照ください。

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7 以上

異常なレスポンス

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

Java

1.4 /identity/silent_image_verification/stateless

このAPIは、サイレント生体認証結果と自撮りの顔写真を比較に利用します。

写真と動画の規格は、のをご参照ください。

リクエストモード

リクエスト URL

リクエストパラメーター

check_qualityは現在、顔が遮られているかどうかのみを評価できます。今後は他の評価項目を導入する可能性があります。

通常のレスポンス

ここで、liveness_statusの結果は以下のようになります。

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7 以上

異常なレスポンス

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

Java

2 写真品質チェック

2.1 /quality/face/stateless

顔写真品質チェックのインターフェースです。

写真ファイルに、複数の顔が含まれることは可能です

顔写真の規格は、運用マニュアルの3章写真と動画の規格をご参照ください。

リクエストモード

リクエスト URL

http://ip:port/quality/face/stateless

リクエストパラメーター

通常のレスポンス

{
    "code": 1000,
    "faces": [
        {
            "rect": { # 顔枠の位置
                "left": integer, # 顔枠の左端の水平座標、写真の左上を原点とする
                "top": integer, # 顔枠の上枠の垂直座標、写真の左上隅を原点とする
                "right": integer, # 顔枠の右端の水平座標、写真の左上隅を原点とする
                "bottom": integer # 顔枠の下枠の垂直座標、写真の左上を原点とする
            "pose": { # ポーズ角度情報
                "yaw": float, # Y 軸角度を示します
                "pitch": float, # X 軸角度を示します
                "roll": float # Z 軸角度を示します
            },
            "occlusion":{ # 顔の遮蔽情報
                "left_eye": float,  # 左目が遮られていない割合, 値 [0,1], 値が大きいほど遮られていない
                "right_eye": float, # 右目が遮られていない割合, 値 [0,1], 値が大きいほど遮られていない
                "nose": float, # 鼻の遮られていない割合、値 [0,1]、値が大きいほど遮られていない
                "mouth": float, # 口の遮られていない割合、値 [0,1]、値が大きいほど遮られていない
                "total": float # 顔の遮られていない総合割合、値 [0,1]、値が大きいほど遮られていない
            },
            "distance2center": float, # 顔から写真の中心までの距離、範囲 [0,1] で、スコアが高いほど、顔が写真の中心に近いことを表します。計算方法：max(1 - 五官中心から写真中心への距離 / 写真の短辺の距離, 0)
            "size": float, # 顔が写真に面積の割合、範囲 [0,1] で、スコアが高いほど、顔の面積割合が大きいことを表します。計算方法：五官が写真に占める面積 / 写真の面積
            "brightness": float, # 顔の明るさのスコア, 範囲は [-1,1] で, スコアが高いほど明るさが高いことを表します
            "sharpness": float, # 鮮明度スコア, 値の範囲 [0,1], スコアが高いほど鮮明になります
            "mouth_open": float, # 口の開き具合, [0,1]の範囲内の値, スコアが高いほど口の開き具合が低くなります
            "integrity": float # 写真中の顔の完全性, 値の範囲 [0,1], スコアが高いほど写真中の顔が完全である、計算式: 写真中の顔の面積 / 顔の面積
        }
    ],
    "request_id": string
}

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

サンプル

curl -X POST "http://ip:port/quality/face/stateless" \
  -d encrypted_image=xxx

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/quality/face/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String encryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));

        params.add(new BasicNameValuePair("encrypted_image", encryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:" +responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

3 なりすまし防止

3.1 /liveness/silent_detection/stateless

サイレント生体検知のインターフェースです。

動画の規格は、のをご参照ください。

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

ここでliveness_statusの結果は以下のようになります：

異常なレスポンス

システムレスポンスコードの説明

可能なHTTPステータスコード

サンプル

1.2 /identity/multiface_image_omni_verification/stateless

比較対象の顔写真に複数の顔が含まれる場合、2つの写真に含まれる顔の各グループの類似度スコアを返します。

写真の規格は、運用マニュアルの3章写真と動画の規格をご参照ください。

リクエストモード

リクエスト URL

http://ip:port/identity/multiface_image_omni_verification/stateless

リクエストパラメーター

通常のレスポンス

例:

{
    "code": 1000,
    "scores": [ # [[a1b1 顔比較スコア, a1b2 顔比較スコア], [a2b1 顔比較スコア, a2b2 顔比較スコア]]
  "face_rects":{ hash,# 各写真の顔枠
        [
            float,
            float,
            float,
            float
        ]
    ],
    "face_rects": { # face frame in each image
        "first_image_face_rects": [ # [[a1 顔枠の座標], [a2 顔枠の座標]]
            [
                int,
                int,
                int,
                int
            ],
            [
                int,
                int,
                int,
                int
            ]
        ],
        "second_image_face_rects": [ # [[b1 顔枠の座標],[b2 顔枠の座標]]
            [
                int,
                int,
                int,
                int
            ],
            [
                int,
                int,
                int,
                int
            ]
        ]
    },
    "request_id": "2c4156bb47794f66a2ed50d5a87e5ca2"
}

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7以上

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

curl -X POST "http://ip:port/identity/multiface_image_omni_verification/stateless" \
  -d first_encrypted_image=xxx \
  -d second_encrypted_image=xxx \
  -d auto_rotate=true

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/multiface_image_omni_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String firstEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));
        String secondEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_02.jpg")));

        params.add(new BasicNameValuePair("first_encrypted_image", firstEncryptedImage));
        params.add(new BasicNameValuePair("second_encrypted_image", secondEncryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:" +responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

1.3 /identity/liveness_image_verification/stateless

インターフェースを介してアップロードされた顔画像と生体認証データを比較して、画像内の顔が同一人物のものであるかどうかを判断します。

写真の規格は、のをご参照ください。

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

{
    "code": 1000,
    "verification_score": float,
    "request_id": string
}

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7 以上

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

curl -X POST "http://ip:port/identity/liveness_image_verification/stateless" \
  -F liveness_file=@/PATH/TO/FILE \
  -d encrypted_image=xxx \
  -d auto_rotate=true

Java

import java.io.BufferedReader;
import java.io.File;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.mime.content.FileBody;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/liveness_image_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        MultipartEntityBuilder entity = MultipartEntityBuilder.create();
        String encryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));

        entity.addPart("liveness_file", new FileBody(new File("src/main/resources/mobile.protobuf")));
        entity.addPart("encrypted_image", new StringBody(encryptedImage));
        entity.addPart("auto_rotate", new StringBody("true"));

        post.setEntity(entity.build());
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:"+responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

1.4 /identity/silent_image_verification/stateless

このAPIは、サイレント生体認証結果と自撮りの顔写真を比較に利用します。

写真と動画の規格は、のをご参照ください。

リクエストモード

リクエスト URL

リクエストパラメーター

check_qualityは現在、顔が遮られているかどうかのみを評価できます。今後は他の評価項目を導入する可能性があります。

通常のレスポンス

ここで、liveness_statusの結果は以下のようになります。

{
    "code": int,
    "passed": boolean,
    "liveness_score": float,
    "liveness_status": string,
    "verification_score": float.
    "image_timestamp": float,
    "base64_image": string,
    "base64_face_image": string,
    "request_id": string
}

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7 以上

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

curl -X POST "http://ip:port/identity/silent_image_verification/stateless" \
  -d encrypted_video=xxx \
  -d encrypted_image=xxx \
  -d auto_rotate=true

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/silent_image_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String encryptedVideo = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/video_01.mp4")));
        String encryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));

        params.add(new BasicNameValuePair("encrypted_video", encryptedVideo));
        params.add(new BasicNameValuePair("encrypted_image", encryptedImage));
        params.add(new BasicNameValuePair("auto_rotate", "true"));
        params.add(new BasicNameValuePair("return_image", "true"));
        params.add(new BasicNameValuePair("return_face_image", "true"));
        params.add(new BasicNameValuePair("return_status", "true"));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:" +responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

1.1 /identity/image_verification/stateless

インターフェースを介してアップロードされた2つの顔写真を比較して、2つの顔が同一人物のものかどうかを判断します。

写真の規格は、運用マニュアルの3章写真と動画の規格をご参照ください。

リクエストモード

リクエスト URL

http://ip:port/identity/image_verification/stateless

リクエストパラメーター

通常のレスポンス

{
    "code": 1000,
    "verification_score": float,
    "request_id": string
}

顔比較スコアのしきい値とエラー率との対応関係

推奨しきい値：0.7以上

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

使用サンプル

Curl

curl -X POST "http://ip:port/identity/image_verification/stateless" \
  -d first_encrypted_image=xxx \
  -d second_encrypted_image=xxx \
  -d auto_rotate=true

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/identity/image_verification/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String firstEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));
        String secondEncryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_02.jpg")));

        params.add(new BasicNameValuePair("first_encrypted_image", firstEncryptedImage));
        params.add(new BasicNameValuePair("second_encrypted_image", secondEncryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:"+responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

3.1 /liveness/silent_detection/stateless

サイレント生体検知のインターフェースです。

動画の規格は、のをご参照ください。

リクエストモード

リクエスト URL

リクエストパラメーター

通常のレスポンス

ここでliveness_statusの結果は以下のようになります：

{
    "code": int,
    "passed": boolean,
    "liveness_score": float,
    "liveness_status": string,
    "image_timestamp": float,
    "base64_image": string,
    "base64_face_image": string,
    "request_id": string
}

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

サンプル

curl -X POST "http://ip:port/liveness/silent_detection/stateless" \
  -d encrypted_video=xxx \
  -d return_status=true \
  -d return_image=true \
  -d return_face_image=true

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/liveness/silent_detection/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String encryptedVideo = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/video_01.mp4")));

        params.add(new BasicNameValuePair("encrypted_video", encryptedVideo));
        params.add(new BasicNameValuePair("return_image", "true"));
        params.add(new BasicNameValuePair("return_face_image", "true"));
        params.add(new BasicNameValuePair("return_status", "true"));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:"+responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}

2.1 /quality/face/stateless

顔写真品質チェックのインターフェースです。

写真ファイルに、複数の顔が含まれることは可能です

顔写真の規格は、運用マニュアルの3章写真と動画の規格をご参照ください。

リクエストモード

リクエスト URL

http://ip:port/quality/face/stateless

リクエストパラメーター

通常のレスポンス

{
    "code": 1000,
    "faces": [
        {
            "rect": { # 顔枠の位置
                "left": integer, # 顔枠の左端の水平座標、写真の左上を原点とする
                "top": integer, # 顔枠の上枠の垂直座標、写真の左上隅を原点とする
                "right": integer, # 顔枠の右端の水平座標、写真の左上隅を原点とする
                "bottom": integer # 顔枠の下枠の垂直座標、写真の左上を原点とする
            "pose": { # ポーズ角度情報
                "yaw": float, # Y 軸角度を示します
                "pitch": float, # X 軸角度を示します
                "roll": float # Z 軸角度を示します
            },
            "occlusion":{ # 顔の遮蔽情報
                "left_eye": float,  # 左目が遮られていない割合, 値 [0,1], 値が大きいほど遮られていない
                "right_eye": float, # 右目が遮られていない割合, 値 [0,1], 値が大きいほど遮られていない
                "nose": float, # 鼻の遮られていない割合、値 [0,1]、値が大きいほど遮られていない
                "mouth": float, # 口の遮られていない割合、値 [0,1]、値が大きいほど遮られていない
                "total": float # 顔の遮られていない総合割合、値 [0,1]、値が大きいほど遮られていない
            },
            "distance2center": float, # 顔から写真の中心までの距離、範囲 [0,1] で、スコアが高いほど、顔が写真の中心に近いことを表します。計算方法：max(1 - 五官中心から写真中心への距離 / 写真の短辺の距離, 0)
            "size": float, # 顔が写真に面積の割合、範囲 [0,1] で、スコアが高いほど、顔の面積割合が大きいことを表します。計算方法：五官が写真に占める面積 / 写真の面積
            "brightness": float, # 顔の明るさのスコア, 範囲は [-1,1] で, スコアが高いほど明るさが高いことを表します
            "sharpness": float, # 鮮明度スコア, 値の範囲 [0,1], スコアが高いほど鮮明になります
            "mouth_open": float, # 口の開き具合, [0,1]の範囲内の値, スコアが高いほど口の開き具合が低くなります
            "integrity": float # 写真中の顔の完全性, 値の範囲 [0,1], スコアが高いほど写真中の顔が完全である、計算式: 写真中の顔の面積 / 顔の面積
        }
    ],
    "request_id": string
}

異常なレスポンス

{
    "code": int,
    "message": string,
    "request_id": string
}

システムレスポンスコードの説明

可能なHTTPステータスコード

サンプル

curl -X POST "http://ip:port/quality/face/stateless" \
  -d encrypted_image=xxx

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

public class HttpClient {
    public static final String POST_URL = "http://127.0.0.1:3000/quality/face/stateless";
    private static AESCipher cipher = new AESCipher("dcbbad6765e14139a07d34b92292a672", "df25d188a061");

    public static void Post() throws Exception {
        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost post = new HttpPost(POST_URL);

        List<NameValuePair> params = new ArrayList<>();

        String encryptedImage = cipher.encrypt(
                Files.readAllBytes(Paths.get("src/main/resources/face_01.jpg")));

        params.add(new BasicNameValuePair("encrypted_image", encryptedImage));

        post.setEntity(new UrlEncodedFormEntity(params));
        HttpResponse response = httpclient.execute(post);

        if (response.getStatusLine().getStatusCode() == 200) {
            HttpEntity respEntity = response.getEntity();
            BufferedReader reader = new BufferedReader(new InputStreamReader(respEntity.getContent()));
            String line = reader.readLine();
            System.out.println(line);
        } else {
            HttpEntity respEntity = response.getEntity();
            String responseString = EntityUtils.toString(respEntity);
            System.out.println("error:" + response.getStatusLine().getStatusCode()
                    + "  " + response.getStatusLine().getReasonPhrase());
            System.out.println("cause of error:" +responseString);
        }
    }

    public static void main(String[] args) throws Exception {
        Post();
    }
}