Mercury Cloud APIは、お客様の安定かつ継続的なビジネスを成長させるために、高可用性と高レベルなセキュリティを備えたサービスを提供します。これらのREST APIを使用することで、お客様のシステムは顔検知、顔品質チェック、顔比較、顔検索、及び特徴DB管理、特徴機能に関する情報を取得・統合し、柔軟的な開発・運用の実現が可能となります。

顔検知

APIは画像内の顔を検出し、顔枠に外接する長方形の座標を返します。同APIを利用することで、顔の角度や性別、年齢、感情など、顔に関連するいくつもの属性を抽出することができます。なお、ここで得られる属性は実際の分類ではなく、AIアルゴリズムによる予測です。

この機能の詳細については、5章をご参照ください。

顔比較

APIは2つの画像の中にあるそれぞれ最大の顔を検出し、これら2つの顔が同じ人物であるかどうかを確認します。顔認証は「1対1」または「1：1」マッチングとも呼ばれます。カメラで撮ったスナップショットと写真付きの書類（例：運転免許証）、または登録済みの画像と照合することによって、検証を行います。

この機能の詳細については、6章をご参照ください。

顔検索

APIは特徴データベースに登録されているすべての顔特徴の中からアップロードした画像から検出された顔を検索し、最も近い結果を返します。顔識別は「1対多」または「1：N」マッチングとも呼ばれます。候補の結果は検索対象の顔特徴との類似性に基づいて返されます。特徴データベースを作成して登録写真をデータベースに追加した後、新しくアップロードされた画像を使用して顔検索を実行できます。

この機能の詳細については、7章をご参照ください。

本マニュアルでは、言語設定が日本語の前提で用語や図が記載されています。その他の言語を設定してご利用になる場合は、用語や図の内容が異なる場合があります。その際は適宜読み替えてご利用ください。

本マニュアルはIT部門に所属するお客様やHTTP/HTTPSベース、JSON形式のWeb APIを利用したアプリケーションの開発・運用経験があるお客様を対象にしています。

4.1 顔特徴

Mercury Cloudでは顔の比較や特徴データベースへ顔の追加、データベースから顔を検索などを行う際、アルゴリズムはアップロードされた生の画像を直接使用することはありません。代わりに画像から顔特徴が抽出され、それを元に処理を行います。

顔特徴とは画像内の顔から抽出された多次元ベクトルで、それぞれの画像の顔から一意の顔特徴が生成されます。類似スコアが示すのは、2つの顔特徴ベクトル間の距離です。したがって、すべてのMercury Cloud OpenAPIドキュメントでは、顔比較または顔検索について言及するときは「顔特徴の比較または顔特徴の検索」を指します。またMercury Cloud OpenAPIは、画像ファイルや画像バイナリを保存することは一切行いません。

4.2 画像エンコーディング

Mercury Cloud APIはHTTPリクエストで、base64でエンコードされたバイナリを使用して画像データを送信します。Linuxを使用している場合はbashコマンドを使用して、画像をbase64文字列に簡単に変換することができます。

def base64_encode_file(file_path):
    handle = open(file_path, "rb")
    raw_bytes = handle.read()
    handle.close()
    return base64.b64encode(raw_bytes).decode("utf-8")

$ base64 file_path

4.3 画像の基準

Mercury CloudにはBase64でエンコードされた画像データを入力として必要とする、以下の5つの重要なAPIがあります。

• 顔検知API（/{app_id}/detect）

• 顔比較API（/{app_id}/compare）

• 品質チェックAPI（/{app_id}/quality）

• 顔特徴追加API（/{app_id}/databases/{db_id}/features）

• 顔検索API（/{app_id}/databases/search）

入力画像の要件はこれらのAPI間で共通であり、次の通りです。

• 画像のフォーマットは、JPG、PNG、BMP、TIFF、またはGIF（最初のフレームのみが受け入れられます）であること。

• 画像のファイルサイズは、8MB未満であること。

• 有効な顔サイズは、32✕32ピクセル以上であること

• バッチアップロードがサポートされている顔検知API（/{app_id}/detect）と顔特徴追加API（/{app_id}/databases/{db_id}/features）では、1回のAPI呼び出しでの画像の数量は16以下であること。

画像の画質が高いほど精度が高くなりますが、画像ファイルのサイズが大きいほどAPIの呼び出し時間が長くなります。 ベストプラクティスとして、APIを呼び出す前に、高品質・正面・鮮明な画像を、有効な顔サイズが200x200ピクセル以上を確保しながら、画像をトリミングして200KB未満に圧縮することを強くお勧めします。

Mercury Cloudは、AIを活用した各種画像解析解析技術を提供するプラットフォームで、高品質なCV PaaSサービス（画像とビデオのアクセスと処理、顔検出、顔検索、クラスタリング、顔認識など）を提供します。柔軟なサービス展開や高いコストパフォーマンスを持ち、サービス可用性、高レベルなセキュリティを備えています。 またクラウドアーキテクチャを採用していることで、安定かつ継続的なビジネス成長の実現に向けた様々なアプリケーションとサービスの連携を可能とするサービスフレームワークも提供します。

3.1 ベースURL

基本サービスエンドポイントはこのような記述です。

https://domain.com/openapi/face/v1

Mercury Cloud APIはデータプライバシーを確保するために、HTTPS経由でのAPIのみ提供しています。

domain.comは、お客様のサービス地域によって異なる場合があります。この情報に関しては、「サービス開始のご連絡」メールで提供されています。

3.2 共通パラメータ

各APIの呼び出しには、いくつかの共通パラメーター、HTTPメソッド、アプリID、アクセスキー、およびシークレットキーが必要です。

GETと POST とDELETE は、Mercury Cloudで使用されるHTTPメソッドです。各APIのメソッドの詳細については、APIリファレンスを参照してください。こちらのHTTPメソッドはAPI認証の部分でも使用されます。

アプリIDやアクセスキー、およびシークレットキーは、「サービス開始のご連絡」メールで提供されています。 これらは安全な場所に保管し、他人に開示しないでください。 これらはAPI URLの設定とAPI認証トークンの計算時に使用されます。

3.3 API認証

すべてのMercuryAPIは、クライアント検証するためにAPI認証トークンを必要とします。各APIを呼び出す際に、2つのヘッダー（x-dateとAuthorization）が必要です。それらが含まれていない場合、401のHTTPエラーコードが表示されます。

x-dateヘッダー

x-dateヘッダーは、RFC-7231形式でのUTC日付と時刻の形式を使用します。

例：

x-date: Fri, 09 Jul 2021 01:51:02 GMT

これは「2021-07-09T01:51:02Z」の時間を示しています。x-dateは現地時間ではなく、GMTタイムゾーンの時間であることにご注意ください。

Authorizationヘッダー

Authorizationヘッダーは指定されたAPIパス、HTTPメソッド、アプリID、アクセスキー、およびシークレットキーに基づいて生成されます。特徴DBに関連する一部のAPIではDB IDも必要となります。Authorizationは次のフォーマットに従います。

Authorization: hmac username="{Access_key}", algorithm="hmac-sha256", headers="x-date request-line", signature="{Signature}"

一般的なAuthorizationヘッダー例は次のとおりです。

Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="

hmac username はアクセスキーです。この例にある005c5acf-5ea9-499c-8d3e-690413f9b5b9 は、お客様のアクセスキーに置換してください。

signature はHMAC-SHA256によって暗号化され、さらにbase64でエンコードされた文字列です。

signature = encode_base64(hmac_sha256(key={secret_key},message=concat("x-date: ", {x-date}, "/n", {method}, " ", {URL path}, " HTTPS/1.1")))

ステップバイステップで手順を説明します。

まず暗号化される前のmessageを組み立てます。暗号化前の一般的なmessageの例は次のとおりです。

x-date: Fri, 09 Jul 2021 01:51:02 GMT
POST /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect HTTP/1.1

x-dateはthe x-date headerで作成される内容と同様です。

POST はHTTPメソッドです。使用するAPIのHTTPメソッドと一致させてください。

/openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect はURLパスです。abc1a8a7-038f-4f9a-b98a-5b602978b135はアプリIDです。ここはお客様のアプリIDに置換ください。またAPIのURLパスも使用するAPIに置換してください。一部のAPIではDB IDも必要です。

例：

x-date: Fri, 09 Jul 2021 01:51:02 GMT
GET /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/databases/aed37153-16b6-4f19-a479-302049e44000 HTTP/1.1

aed37153-16b6-4f19-a479-302049e44000 はDB IDです。

シークレットキーblFWSvhp9pRz2JnRHnfvkFeAuApClhKgを使用して、最初に作成した以下のメッセージを暗号化にします。

x-date: Fri, 09 Jul 2021 01:37:00 GMT
POST /openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect HTTP/1.1

以下の内容が出力されます。

91427a38788c301667c604846b6011c550258230b69338de7598313b3d3b8be6

最後にbase64でエンコードすると、signatureは次のように完成されます。

kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y=

このsignatureを使用すると、上記と同じようなのAuthorizationヘッダーが完成されます。

Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="

これで、x-date HeaderとAuthorization Headerを利用して、/openapi/face/v1/{app_id}/detectのAPI呼び出しができます。

curl -X POST -d {} 'https://domain.com/openapi/face/v1/abc1a8a7-038f-4f9a-b98a-5b602978b135/detect' \
-H 'x-date: Fri, 09 Jul 2021 01:37:00 GMT' \
-H 'Authorization: hmac username="005c5acf-5ea9-499c-8d3e-690413f9b5b9", algorithm="hmac-sha256", headers="x-date request-line", signature="kUJ6OHiMMBZnxgSEa2ARxVAlgjC2kzjedZgxOz07i+Y="'

3.4 ヘッダー作成ツールサンプル

import base64
import datetime
import hashlib
import hmac
import urllib.parse

def generate_authorization_headers(access_key, secret_key, url, http_method):
    RFC7231_FORMAT = '%a, %d %b %Y %H:%M:%S GMT'
    xdate = datetime.datetime.utcnow().strftime(RFC7231_FORMAT)
    url_path = urllib.parse.urlparse(url).path
    signature = 'x-date: %s\n%s %s HTTP/1.1' % (xdate, http_method.upper(), url_path)
    crypto = hmac.new(secret_key.encode('utf-8'), signature.encode('utf-8'), hashlib.sha256)
    hmac_signature = base64.b64encode(crypto.digest()).decode('utf-8')
    authorization = '''hmac username="%s", algorithm="hmac-sha256", headers="x-date request-line", signature="%s"''' % (access_key, hmac_signature)
    return {
        "x-date": xdate,
        "Authorization": authorization
    }

//crypto-jsが必要です。 詳細はhttps://www.npmjs.com/package/crypto-jsを参照してください。

function generate_authorization_headers(access_key, secret_key, url, http_method) {
    var today = new Date();
    var xdate = today.toGMTString();
    var reg = /.+?\:\/\/.+?(\/.+?)(?:#|\?|$)/;
		var url_path = reg.exec(url)[1];
    var signature = "x-date: " + xdate + "\n" + http_method + " " + url_path + " HTTP/1.1";
    var hmac_signature = CryptoJS.HmacSHA256(signature, secret_key).toString(CryptoJS.enc.Base64);
    var authorization = "hmac username=\"" + access_key + "\", algorithm=\"hmac-sha256\", headers=\"x-date request-line\", signature=\"" + hmac_signature +  "\"";
    return "-H 'x-date: " + xdate + "' -H 'Authorization: " + authorization + "'";
}

import java.text.SimpleDateFormat
import java.util.*
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.net.URL

fun generate_authorization_headers(
     access_key: String,
     secret_key: String,
     url: String,
     http_method: String): Pair<String, String> {
    val rfc7231 = SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss 'GMT'", Locale.US).apply {
        isLenient = false
        timeZone = TimeZone.getTimeZone("UTC")
    }
    val xDate = rfc7231.format(Date())
    val url_path = URL(url).getPath()
    val encodeData = "x-date: $xDate\n$http_method $url_path HTTP/1.1"
    val sha256Hmac = Mac.getInstance("HmacSHA256")
    val secretKey = SecretKeySpec(secret_key.toByteArray(), "HmacSHA256")
    sha256Hmac.init(secretKey)
    val signature = Base64.getEncoder().encodeToString(sha256Hmac.doFinal(encodeData.toByteArray()))
    val authorization = "hmac username=\"${access_key}\", algorithm=\"hmac-sha256\", headers=\"x-date request-line\", signature=\"${signature}\""
    return Pair(xDate,authorization)
}

3.5 SwaggerHubで"Try it out"

SwaggerHubでは、「Try it out」ボタンを使用してブラウザーから直接API呼び出しをテストできるインタラクティブな方法を提供しています。Mercury Cloud Interactive APIドキュメントでは、この機能を使用する前に特別な認証を行うことが必要です。ここでは、Mercury Cloud InteractiveAPIドキュメントの「Try it out」機能を使用するための方法を解説します。

3.5.1 ヘッダーを準備

ヘッダー作成ツールで、x-dateヘッダーとAuthorizationヘッダーを準備します。

3.5.2 サーバーを選択

"Servers"のドロップダウンリストをクリックして、サービスエリアに応じたサーバーを選択してください。

3.5.3 Authorizationヘッダーで認証

サーバーリストの右側にある「Authorize」ボタンをクリックしてください。

次の画面が表示されます。Authorizationヘッダーを「Value」に貼り付けて、「Authorize」ボタンをクリックしてください。

これでAuthorizationヘッダーが設定されました。再認証するには「Logout」ボタンをクリックして、上記の手順をやり直してください。

3.5.4 パラメータを入力して試してみてください

これでAPI呼び出しを試すことができます。 List Feature DatabaseのAPIを例として試してみます。

「Try it out」ボタンをクリックすると「Execute」ボタンが表示されます。x-dateとapp_idパラメータを入力し、「Execute」ボタンをクリックしてください。

APIのレスポンスおよびいくつかの関連情報が表示されます。

顔比較APIは、2つの画像からそれぞれ最大の顔を検出し、これら2つの顔が同じ人物であるかどうかを確認します。顔認証は「1対1」または「1：1」マッチングとも呼ばれます。カメラで撮ったスナップショットと、写真付きの書類（例：運転免許証）、または登録済みの画像と照合することによって、検証を行います。

以下の手順では、2つの画像をアップロードして各画像内で最大の顔を検出し、2つの顔が同じ人物である可能性を比較します。 正常に検出された場合、比較結果と検出された顔情報が返されます。

6.1 準備

まず、Python環境がインストールされていることを確認してください。

次のPythonファイルをダウンロードして、Pythonのパスフォルダーにコピーしてください。

api_parameters.pyをテキストエディターで開き、パラメーターをお客様の情報に置き換えてください。詳細は3.2節をご参照ください。

api_parameters.pyをテキストエディターで開き、パラメーターをお客様の情報に置き換えてください。詳細は3.2節をご参照ください。

# Common parameters. Used for all API calls.
# Base URL for Mercury Open API.
api_url = "https://mercury.japancv.co.jp/openapi/face/v1"
# Provision App Id for API calls.
app_id = "aabbccdd-eeff-0011-2233-445566778899"
# Provision access key to authentication.
access_key = '00112233-4455-6677-8899-aabbccddeeff'
# Provision secret key to authentication.
secret_key = '13579acegijmoqsuwyACEGIJMOPSUWY'

6.2 顔比較リクエスト送信

次のコマンドで、顔比較のAPIリクエストを送信し、2つの画像の最大の顔を比較します。パスをPythonライブラリパスと画像ファイルのパスにそれぞれ置き換えてください。

python {python_path}\compare_images.py "{image_path}\image1.jpg" "{image_path}\image2.jpg"

結果の例は次のようになります。 顔が検出されたかどうかを示す検出resultsフィールドに、検出された顔の詳細が含まれます。比較結果として、2つの顔の類似度を表すscoreフィールドと、顔検知結果を含むone_faceとanother_faceフィールドが含まれます。

Compare image: {image_path}\image1.jpg {image_path}\image2.jpg
https://mercury.japancv.co.jp/openapi/face/v1/aabbccdd-eeff-0011-2233-445566778899/detect
Http status code: 200
Similarity: 0.9915448
Detect face. rectangle: {'top': 625, 'left': 350, 'width': 793, 'height': 818} angle: {'yaw': -0.42474133, 'pitch': 9.596367, 'roll': 0.07245465}
Predicted attributes:
        Age: 29 ~ 39
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE
Detect face. rectangle: {'top': 637, 'left': 276, 'width': 844, 'height': 834} angle: {'yaw': 4.691873, 'pitch': 10.485169, 'roll': 1.0859865}
Predicted attributes:
        Age: 28 ~ 38
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE

ここのSimilarityは、2つの顔が同じ人物がどうかの信頼水準を表します。この例では、99.15％が同じ人物であることを確信できます。

6.3 しきい値と精度

お客様はご自身でその許容レベル（通常「しきい値」と呼ばれる）を決定して、類似性スコアと比較し、顔認証の最終結果を判断する必要があります。そのロジックはご自身のプログラムに組み込まれる必要があります。Mercury Cloudはそれを決定することはできません。

しきい値によっては、顔認証の結果が異なる場合があります。例えばしきい値が0.995に設定された場合、scoreが比較的高いと見なされますが、前述の結果を例にすると0.9915448<0.995のため、同一人物である仮説を受け入れることができます。逆にしきい値が0.95に設定された場合、0.9915448>0.95のため、同一人物である仮説を受け入れることができます。

しきい値の設定は、他人受入率（FAR）と本人拒否率（FRR）の間のトレードオフです。しきい値が高いほど、誤って拒否が発生する可能性が高くなり、誤って受け入れが発生する可能性が低くなります。

ビジネスによって、顔比較の利用シーンが異なり、認識精度に対する要求も異なります。一般的シーンでは可能な限り他人誤受入（FAR）を回避するため、しきい値を0.6から0.7の間に設定されます。 ただし、必ずお客様のビジネス要件とテスト結果に合わせて、ご自身でしきい値の調整を行ってください。

更新スケジュールはステータスページをご参照ください。

既知の問題

• 顔検索APIで複数の顔が写っている画像を検知する際、すべての顔を検出できない場合があります。その場合、このAPIを使用する前に画像をトリミングし、顔が1つだけ写っているように修正したうえで顔検知APIを使用することを推奨します。

• 品質チェックAPIで画像の最適回転角度を検知する際、一部の画像が間違っている回転角度を返される場合があります。現在認証精度の向上するため、アルゴリズムの改修を進めております。

• max_sizeが100Kを超える特徴データベースに、同じ画像が5回以上追加・削除された場合、類似の特徴が登録されていても、顔検索（1vN）APIのレスポンスが、空のセットになる可能性があります。 この問題を回避するには、max_sizeが小さい特徴データベースを作成するか、同じ画像を複数回の追加・削除を回避してください。

顔検索APIは、特徴データベースに登録されているすべての顔特徴の中からアップロードした画像から検出された顔を検索し、最も近い結果を返します。顔識別は「1対多」または「1：N」マッチングとも呼ばれます。候補の結果は検索対象の顔特徴との類似性に基づいて返されます。特徴データベースを作成して登録写真をデータベースに追加した後、新しくアップロードされた画像を使用して顔検索を実行できます。

以下の手順では、特徴データベースを作成して特徴データベースにいくつかの顔特徴を追加し、検索画像をアップロード。画像内の最大の顔を検出してから、1つの特徴データベース内で類似する顔を検索します。正常に検出された場合、比較結果と検出された顔情報が返されます。そして最後に、特徴データベースが削除されます。

各APIが特徴データベースを操作する際、db_idは1つの特徴データベースを識別するための一意のキーです。特徴データベース作成API（POST / {app_id} /データベース）の応答内容の中にあるdb_idを記憶するか、特徴データベース一覧API（GET / {app_id} /データベース）で見つけることができます。

7.1 準備

まず、Python環境がインストールされていることを確認してください。

次のPythonファイルをダウンロードしてPythonのパスフォルダーにコピーしてください。

api_parameters.pyをテキストエディターで開き、パラメーターをお客様の情報に置き換えてください。詳細は3.2節をご参照ください。

# Common parameters. Used for all API calls.
# Base URL for Mercury Open API.
api_url = "https://mercury.japancv.co.jp/openapi/face/v1"
# Provision App Id for API calls.
app_id = "aabbccdd-eeff-0011-2233-445566778899"
# Provision access key to authentication.
access_key = '00112233-4455-6677-8899-aabbccddeeff'
# Provision secret key to authentication.
secret_key = '13579acegijmoqsuwyACEGIJMOPSUWY'

7.2 特徴データベースを作成

次のコマンドで特徴データベース作成のAPIリクエストを送信し、「hoge」という名前でDBサイズが1000の特徴データベースを作成します。パスをPythonライブラリパスに置き換えてください。 DBサイズは、1つの特徴データベースに保存できる顔特徴の最大数を制限します。この数量は、お客様がご購入したサブスクリプションで許容しているID数を超えられないので、ご注意ください。

python {python_path}\create_feature_db.py hoge 1000

APIを送信後、結果は次のようになります。ここには一意のdb_idが含まれます。

Compare feature database: name: hoge max size: 1000
Http status code: 200
response: {
 "trace_id": "de2557f6b435c836dd12447413bc9966",
 "name": "hoge",
 "db_id": "4caf27d2-f621-4cbf-acec-a7553f226000",
 "object_type": "OBJECT_FACE",
 "feature_version": 24902,
 "description": "Description for database hoge",
 "created_at": "2021-07-15T04:11:04.744807758Z",
 "max_size": 1000,
 "size": 0
}

このdb_idは忘れずに記録しておいてください。 それ以後の他のAPIを呼び出すときに使用されます。

7.3 特徴データベースの一覧表示

次のコマンドで、特徴データベースの一覧を表示するAPIリクエストを送信し、先ほど作成した特徴データベースの存在を確認します。

python {python_path}\list_feature_db.py

結果は次のようになります。

List feature databases:
Http status code: 200
db_ids: [
 "4caf27d2-f621-4cbf-acec-a7553f226000"
]

同じdb_idの特徴データベースが返されることを確認できます。

7.4 画像品質チェック

品質チェックAPIは、顔のサイズ、角度、明るさ、鋭さ、遮蔽などを分析し、すべての要素の値を応答します。顔特徴を特徴データベースに追加する前に、画像の品質チェックを行うことを強く推奨します。これは画質が高いほど認識精度が高くなるためです。

次のコマンドで、品質チェックのAPIリクエストを送信します。

python {python_path}\check_quality.py "{image_path}\image.jpg"

結果は次のようになります。

Check quality: {image_path}\image.jpg
Http status code: 200
Quality results: {
 "angle": {
  "yaw": 0.0027652662,
  "pitch": 7.864833,
  "roll": 0.049663484
 },
 "quality": {
  "distance2center": 0.08779055,
  "size": 0.36317098,
  "brightness": 0.17242007,
  "sharpness": 1,
  "mouth_open": 0.018774271,
  "missing": 1,
  "align_score": 9.999992
 },
 "occlusion": {
  "eye": 0,
  "nose": 0,
  "mouth": 0,
  "eyebrow": 0,
  "face_line": 0,
  "occlusion_total": 0
 },
 "rectangle": {
  "top": 610,
  "left": 332,
  "width": 777,
  "height": 774
 }
}

お客様はご自身でその許容レベルを決定して、判断する必要があります。そのロジックはご自身のプログラムに組み込まれる必要があります。

ここではパスポート写真の画質に近似する参考値を提供します。ただしお客様のビジネス要件とテスト結果に基づいて、しきい値を調整およびプログラムを構成してください。

パスポート写真の品質基準

7.5 特徴データベースに画像を追加

顔特徴一括追加APIは複数の顔特徴を追加するために、1つのリクエストで特徴データベースに複数の画像から送信します。特徴データベースに追加された各顔特徴は、一意のfeature_idがを割り当てされます。同一の画像または同じ人物に属する複数の画像を特徴データベースに複数回追加する場合、いくつかの異なるfeature_idが割り当てされます。 つまりfeature_idは1人の人間と同等に必要はなく、その時点で追加された顔特徴になります。

次のコマンドで、特徴データベースに顔特徴を追加のAPIリクエストを送信し、指定したフォルダー内のすべての画像を、先ほど作成した特徴データベースに追加します。

python {python_path}\add_faces.py "4caf27d2-f621-4cbf-acec-a7553f226000" {image_path}

結果は次のようになります。ここでは2枚の写真を送信しました。

Add to database: 4caf27d2-f621-4cbf-acec-a7553f226000 image: {image_path}\image1.jpg
Http status code: 200
Face feature_id: 4caf27d2f6214cbfaceca7553f226001000000000000008e
Detect face. rectangle: {'top': 625, 'left': 350, 'width': 793, 'height': 818} angle: {'yaw': -0.42474133, 'pitch': 9.596367, 'roll': 0.07245465}
Predicted attributes:
        Age: 29 ~ 39
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE
Add to database: 4caf27d2-f621-4cbf-acec-a7553f226000 image: {image_path}\image2.jpg
Http status code: 200
Face feature_id: 4caf27d2f6214cbfaceca7553f226001000000000000008f
Detect face. rectangle: {'top': 637, 'left': 276, 'width': 844, 'height': 834} angle: {'yaw': 4.691873, 'pitch': 10.485169, 'roll': 1.0859865}
Predicted attributes:
        Age: 28 ~ 38
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE

2つの画像の顔特徴が特徴データベースに追加されました。

7.6 特徴データベースで顔検索

顔検索APIは画像をアップロードし、検証スコアの結果に基づいて特徴データベース内の上位K個の類似した顔特徴を検索します。ここで提供するサンプルコードは、検証スコアが0.8を超える上位2つの顔特徴に制限します。

次のコマンドで、顔検索のAPIリクエストを送信します。

python {python_path}\search_faces.py "4caf27d2-f621-4cbf-acec-a7553f226000" "{image_path}\image.jpg"

結果は次のようになります。

Search face: {image_path}\image.jpg in:  4caf27d2-f621-4cbf-acec-a7553f226000
Http status code: 200
Detect face. rectangle: {'top': 342, 'left': 171, 'width': 384, 'height': 392} angle: {'yaw': -1.557804, 'pitch': 10.313386, 'roll': 1.3425148}
Predicted attributes:
        Age: 28 ~ 38
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE
        db_id: 4caf27d2-f621-4cbf-acec-a7553f226000
top 1 score: 0.9813498
        feature: {'feature_id': '4caf27d2f6214cbfaceca7553f226001000000000000008e', 'key': '', 'extra_info': 'image1.jpg'}
top 2 score: 0.9803276
        feature: {'feature_id': '4caf27d2f6214cbfaceca7553f226001000000000000008f', 'key': '', 'extra_info': 'image2.jpg'}

近似するものが見つかった場合、APIの応答には上位K件の結果が含まれます。 それ以外の場合、結果は返されません。この例では、前の手順で追加された2つの画像と検索画像は同一人物であるため、feature_idsとそのスコアが返されます。

7.7 特徴データベース削除

最後に特徴データベースが不要になった場合は、特徴データベースを削除することを推奨します。削除することで特徴データベースに登録されているすべての顔特徴は、同時に削除されます。 次のコマンドを使用して、削除を実行するAPIを送信します。

python {python_path}\delete_feature_db.py "4caf27d2-f621-4cbf-acec-a7553f226000"

結は次のようになります。

Delete feature database: db_id: 4caf27d2-f621-4cbf-acec-a7553f226000
Http status code: 200
response: {
 "trace_id": "81c28dcd71c48befdcd2d92afb34c278"
}

特徴データベースおよび追加されたすべての顔特徴は、Mercury Cloud環境から完全に削除されました。

顔検知APIは画像内の顔を検出し、顔枠を外接する長方形の座標を返します。同APIでは、顔の角度、性別、年齢、感情など、顔に関連するいくつかの属性も抽出できます。すべての属性は実際の分類ではなく、AIアルゴリズムによる予測によるものです。

以下の手順では1枚の画像をアップロードし、画像内の顔を検出する方法を記載しています。正常に検出された場合、検出された顔情報が返されます。

5.1 準備

まず、Python環境がインストールされていることを確認してください。次に、下記のPythonファイルをダウンロードしてPythonのパスフォルダーにコピーしてください。

api_parameters.pyをテキストエディターで開き、パラメーターをお客様の情報に置き換えてください。詳細は3.2節をご参照ください。

api_parameters.pyをテキストエディターで開き、パラメーターをお客様の情報に置き換えてください。詳細は3.2節をご参照ください。

# Common parameters. Used for all API calls.
# Base URL for Mercury Open API.
api_url = "https://mercury.japancv.co.jp/openapi/face/v1"
# Provision App Id for API calls.
app_id = "aabbccdd-eeff-0011-2233-445566778899"
# Provision access key to authentication.
access_key = '00112233-4455-6677-8899-aabbccddeeff'
# Provision secret key to authentication.
secret_key = '13579acegijmoqsuwyACEGIJMOPSUWY'

5.2 顔検知リクエスト送信

次のコマンドを使うことで、顔検出のAPIリクエストを送信し、その画像内の顔を検出することができます。パスは、Pythonライブラリパスと画像ファイルのパスにそれぞれ置き換えてください。

python {python_path}\detect_faces.py "{image_path}\image.jpg"

結果は次のようになります。顔が検出されたかどうかを示す検出resultsフィールドに、検出された顔の詳細が含まれています。

Detect image: {image_path}\image.jpg
Http status code: 200
Detect face. rectangle: {'top': 625, 'left': 350, 'width': 793, 'height': 818} angle: {'yaw': -0.42474133, 'pitch': 9.596367, 'roll': 0.07245465}
Predicted attributes:
        Age: 29 ~ 39
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE

ここでのHAT_STYLE_TYPE_NONEは、検出された顔に帽子/キャップが着用されていないことを意味します。TRANSPARENT_GLASSESは、検出された顔に通常の眼鏡（サングラスではない）を着用されていないことを意味します。COLOR_TYPE_NONEは、検出された顔にマスクが着用されていないことを意味します。

詳細は、2章で提供されている最新バージョンのYAMLファイルまたはオンラインAPIマニュアルを参照してください。

表：属性

8.1 画像の上級使用方法

通常、画像関連のAPIでは1つの画像から1つの顔だけが使用されますが、Mercury Cloudは様々なユーザーシナリオのニーズに合わせた、より強力な機能を提供しています。

8.1.1 画像内の範囲指定

シナリオによっては画像全体から顔を検出するのではなく、画像の特定の領域を検出したい場合があります（例えば身分証明書など）。そのため一部のAPIでは、長方形の範囲を指定することができます。長方形で範囲を指定すると、APIはその範囲のみ顔をスキャンして結果を返します。長方形の指定がない場合、画像全体がスキャンされます。なお、長方形の領域を指定すると、特にHD画像の場合、指定しないより処理速度が速くなります。

リクエスト例

8.1.2 複数の顔検知

顔検知機能は、顔検知API、顔比較API、顔特徴一括追加API、および顔検索APIで使用されます。 ただし検出動作は少し異なります。顔検知APIでは画像内の検出可能なすべての顔をスキャンします。画像に複数の顔が含まれている場合、顔検知APIは画像内のすべての顔を検出できます。APIレスポンスのbatchs.facesは、画像で検出されたすべて顔を含むリストです。

顔比較API、品質チェックAPI、顔特徴一括追加API、および顔検索APIでは、画像内の最大の顔のみを使用します。

リクエスト例

8.1.3 一括画像処理

顔検知APIではリクエストのimages フィールドとレスポンスのresultsフィールド、batchesフィールドはすべてリストタイプです。これらのリストには、複数の画像を含めることができます。リクエスト内のimagesフィールドの順序と応答のresultsフィールド、batchesフィールドの項目の順序は一致しています。同じインデックス値を使用して、画像、検出結果、および検出された顔へのアクセスができます。

8.2 KeyとExtra Infoの上級使用方法

特徴データベースに顔特徴を追加するときは、画像と共にkey、またはextra_info値を追加することを推奨します。これにより、追加された顔特徴をfeature_idより可読性が高い方法で管理とアクセスができます。顔特徴を特徴データベースに複数回追加すると複数のfeature_idを受け取り、データベースに重複した顔特徴が存在する可能性があります。keyまたはextra_info値がないと、feature_idが紛失した場合の管理が困難になりますので、ご注意ください。

8.2.1 Key

顔特徴のKeyは、アルファベット、数字、ハイフン（ "-"）、最大半角48文字で構成されるユーザー定義の文字列です。顔特徴を特徴データベース内で人間として扱う場合、keyはその人間のインデックスです。feature_idで顔特徴にアクセスすることで、その顔特徴のkeyとextra_infoを取得することもできます。keyの値は、必ずしもすべての特徴データベースで一意である必要はありません。したがって一連の顔特徴に同じkeyの値を設定することもできます。

ほとんどのお客様システムでは、ユーザーごとに一意のuser_id（たとえば、従業員番号やメンバーシップ番号）を配布します。この一意のuser_idは、顔特徴一括追加APIのリクエストの中、key値として設定することで、ユーザーシステムのuser_idとMercury Cloudの顔特徴をマッピングできます。Mercury Cloudではなく、お客様のユーザーシステムは、特徴データベース全体でkeyの一意性を維持する責任があります。

顔検索（1：N）APIのレスポンスには、検索画像の顔特徴と比較して最も類似性の高い上位の結果が含まれます。結果のKeyは、最も類似した顔特徴の所有者をすばやく特定することに役立ちます。そして、その登録者に対して、更なるビジネスロジックの実装と処理を俊敏的に実行できます。

8.2.2 Extra Info

Mercury Cloudは、登録者情報を格納するための専用のカラムを提供していません。かわりに、より柔軟で高度なソリューションを提供します。extra_infoフィールドはユーザー定義の文字列であり、最大半角1,024文字を格納できます。シリアル化されたJSONオブジェクト、Base64でエンコードされたバイナリ、画像のURLなど、任意の文字列タイプを含めることができます。例えば1つのメンバーシップサービスの情報は、次のように構成できます。

この例では名前と画像のURLがextra_infoに含まれているため、お客様システムのデータベースでクエリを実行しなくても、登録済みの名前と登録画像をすばやく抽出できます。

頻繁に使用する情報のみ、extra_infoとMercuryCloudに保存することを強く推奨します。Mercury Cloudはテナントの分離とデータセキュリティを確保するための高レベルなセキュリティ対策を提供していますが、ベストプラクティスとしては機密性の高い個人情報の保存は控えるようにしてください。

V1.5.0から、extra_info は特徴の追加情報を更新APIで更新できます。

8.3 顔検索の上級使用方法

顔検索APIは、1：Nの顔検索シナリオで最も重要なAPIです。カメラで撮影した写真と一致する人物の結果を見つけるために、特徴データベースに登録されている顔検索と比較されます。

8.3.1 検索スコアについて

顔特徴は多次元ベクトルです。顔検索シナリオではAPIは特定の顔特徴を特徴データベース内の登録済みの顔特徴と比較し、それぞれがどれほど近いかを計算します。0〜1の範囲のAPI応答のスコアは、それらの間の類似性を示します。様々な条件、画像、角度、明るさ、撮影した日付などが検証スコアに影響します。2つ同じの画像を比較しても、スコアは1に非常に近いものの、類似性スコアに1にはなりません。

8.3.2 Min scoreとTop K

顔検索APIリクエストを送信する場合、min_scoreフィールドをしきい値として使用して、レスポンス応答の最低スコアを制限できます。min_score以上の結果のみが返されます。ただしお客様がご自身でmin_scoreを決定する必要があります。一般的なしきい値は、FARをできるだけ回避する観点で、0.94から0.96に設定されますので、ご自身のビジネス要件とテスト結果に基づいて、調整およびシステム構成をしてください。

もう1つのフィールドtop_kは、APIによって返される結果の数を制限するために使用されます。ほとんどの場合、上位1つの結果のみが必要です。ただし一部の場合では、より多くの上位結果を取得するとする必要があります。min_score設定の優先度はtop_kよりも高いことに注意してください。つまり、上位k個の顔特徴のいずれかがmin_score要件を満たしていない場合、APIレスポンスには含まれません。

8.3.3 複数特徴DBの検索

一部のシナリオでは、複数の機能データベースに顔特徴を保存したい場合があります。例えば、地域ごとに仕分ける場合などです。

通常、顔検索APIは単一の特徴データベースで実行されます。ただし特殊な場合には、すべての特徴データベースを検索する必要があります。Mercury Cloudの顔検索APIは、複数のdb_idをサポートすることでこの機能を提供できます。APIは複数の特徴データベースにわたって顔特徴を検索し、上位の結果をレスポンスします。

APIリクエストのdb_id数がNに設定されている場合、単一データベースに対する顔検索をN回実行することと同等のため、複数データベースでの顔検索はネットワーク遅延を増加させることにご注意してください。

2022年5月現在、各地域のバージョン情報は以下です。

• 日本：V1.5.0

• アメリカ：V1.5.0

• バーレーン：V1.5.0

2.1 Mercury Cloud OpenAPI ファイル

以下のリンクより、最新版のMercury CloudのYAMLファイルをダウンロードできます。

2.2 オンラインAPIドキュメント

以下のリンクをクリックすると、最新のMercury Cloud OnlineAPIドキュメントにアクセスできます。