1.4 /identity/silent_image_verification/stateless

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

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

リクエストモード

POST

リクエスト URL

http://ip:port/identity/silent_image_verification/stateless

リクエストパラメーター

フィールド	型	必須	説明
encrypted_video	string	Yes	暗号化された動画。暗号化方法の参照: 個人データの暗号化
encrypted_image	string	Yes	暗号化された画像 。暗号化方法の参照: 個人データの暗号化
auto_rotate	boolean	No	デフォルト値はfalseで、画像が回転していないことを示します。値がtrueの場合、画像は自動的に回転されます
check_quality	boolean	No	デフォルト値がfalseの場合は品質チェックを行わず、trueの場合は画像の品質チェックを行います
return_image	boolean	No	選出されたフレーム画像と選出されたフレーム画像のタイムスタンプを返すかどうかを指定します。 デフォルト値はfalseで、値がtrueかつ生体認証が通過した場合にimage_timestamp,base64_image フィールドが返されます
return_face_image	boolean	No	選出されたフレーム画像の顔のクロップを返すかどうかを指定します。 デフォルト値はfalseで、値がtrueかつ生体認証が通過した場合にbase64_face_imageフィールドが返されます
return_status	boolean	No	エラーステータスの説明を返すかどうかを指定します。デフォルトはfalseで、liveness_statusフィールドは値がtrueの場合のみ返されます

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

通常のレスポンス

フィールド	型	説明
code	int	システムレスポンスコード：1000
passed	boolean	生体認証に通過したかどうか
liveness_score	float	サイレント生体認証のスコア（参考までに、結果はpassedフィールドを使用してください）
liveness_status	string	サイレントライブネス検出のエラー状態を記述します。このフィールドは、return_status=trueの時に返されます
verification_score	float	顔照合スコア、おすすめのしきい値： > 0.7。このフィールドはpassed=trueの場合に返されます
image_timestamp	float	選出されたフレームのタイムスタンプを秒単位で表し、passed=true、return_image=trueの場合に返されます
base64_image	string	選出されたフレーム画像。passed=true、return_image=trueの場合は該当フィールドを返します
base64_face_image	string	選出された顔写真の切り抜き。passed=true、return_face_image=trueの場合に返されます
request_id	string	リクエストのID

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

ステータス	説明
ok	サイレント生体認証は合格：動画の中の人は実在する
hack	サイレント生体認証は不合格。理由：捏造した顔（例えば, ビデオで撮影された顔など）
short_time	サイレント生体認証は不合格。理由：ビデオの持続時間は2s未満など

{
    "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.4	0.5	0.6	0.7	0.8	0.9
エラー率	1/10	1/100	1/1000	1/10,000	1/100,000	1/1,000,000

推奨しきい値：0.7 以上

異常なレスポンス

フィールド	型	説明
code	int	システムレスポンスコード
message	string	エラーメッセージ
request_id	string	リクエストのID

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

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

コード	フィールドの値	説明
1200	invalid argument	無効な入力パラメーター
2003	invalid image size	画像サイズ（幅と高さのピクセル数）が要件を満たしていません
2004	invalid content length	画像のファイルサイズが要件を満たしていません
2005	invalid image type or corrupted	画像タイプが要件を満たしていません
4000	detection failed	特徴の抽出に失敗しました。画像に顔が検出されませんでした
4004	face occlusion	顔は検出されるが、目、鼻、口が部分的に見えません
4007	liveness silent check failed	サイレント生体認証に失敗しました

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

ステータスコード	ステータスフィールド
400	BAD_REQUEST
404	NOT_FOUND
411	LENGTH_REQUIRED
413	PAYLOAD_TOO_LARGE
500	INTERNAL_ERROR

使用サンプル

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();
    }
}