リクエストとレスポンス文

画像

画像（images）は、画像からの生体検知APIで必須のJSON形式の配列です。各項目には、さまざまな入力の種類とモデルに対応するためのインデックス（index）、画像の種類（type）、およびデコードされた画像データ（data）が含まれます。

📘

画像ファイルの保存について

Livenessでは、ユーザーがアップロードした画像ファイルまたは画像データは、いかなる状況でもどこにも保存されません。Base64エンコードされた画像データは、生体検知後に即破棄されます。

インデックス

インデックス（index）は、画像項目の順序を表す必須の整数フィールドです。Livenessは、様々な種類のモデルを扱えるため、複数の入力画像のシーケンスに対応する必要があります。リクエスト内のindexは常に0から始まり、整数で増分する必要があります。余分な画像の送信はサービス側で無視され、エラーにはなりません。リクエスト側、レスポンス側双方の負担が大きくなりますのでお控えください。

種類

種類（Type）は、画像項目の種類を表す必須の文字列フィールドです。Livenessは、様々な種類のモデルを扱えるため、複数の入力画像の種類に対応する必要があります。画像の種類一覧はこちら。こちらのリストは、新しいモデルの導入によって拡張されます。

データ

APIで送信されるすべての画像データは、base64でエンコードする必要があります。Livenessでは、その機能を提供しません。ご自身のサービスに実装してください。ここでは、base64エンコーディングの2つの簡単な例を提供します。

import base64

# ファイルを読み取り、バイナリを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

エンコードされた文字列は、文字列値としてimages[i].dataフィールドに入れてください。省略したりNullにしたりすると、エラーが発生します。以下は短縮された例です。

{
  "images": [
    {
    	"index": 0,
      "type": "RGB",
      "data": "/9j/4AAQSkZJRgAB="
    }
  ]
}

自動回転

🚧

リソースを消費するプロセス

このオペレーションは、標準のリクエストよりも余分なリソースを消費するため、遅延が高くなります。
機能を十分に理解した上でご利用ください。

画像のExif（エクスチェンジャブル・イメージ・ファイル・フォーマット）メタデータに画像の向き情報が含まれている場合があります。通常、OSは画像を表示するときにExif情報に従って自動的に向きを調整するため、画像が縦向きになっていることを誤解されやすいです。これらの画像をそのままエンコードされてサービスに送信されると、多くの場合では、モデルが認識できず、顔が見つからないエラーを返します。まれに、間違った向きの画像がモデルによって受け入れられ、誤って処理される可能性があります。その場合の認識精度は保証できません。

間違った向きの画像を入力することを避けるために、画像データを送信するときにautoRotateフィールドをtrueに指定することで、システムは画像を正しい向きで自動的に調整して処理できます。

📘

画像がエンドユーザーから送信されたときに自動回転を推奨します

お客様のシステムまたはアプリケーション側が入力画像を制御できないか、画像の前処理機能を持たない場合、自動回転機能を有効にすることを推奨します。

位置

positionフィールドには、顔認識の際に顔の位置を指定するエリアの4つの整数値により構成されます。topとleftの値は、左上の座標点のピクセル値となります。widthとheightの値を使用すると、画像内で顔エリア位置の長方形を指定できます。

Livenessは複数の顔を含める画像も受け入れることができるため、positionでどの顔が処理されたかを理解することは非常に重要です。AnySeeとLivenessの顔検出ロジックはどちらも画像内の最大の顔のみを検出して処理するものと同じであるため、両方のサービスで同じ画像をそのまま使用しても安全です。

1回のリクエストで複数の画像をアップロードする場合、positionは最初の入力画像の顔位置のみを表します（あるいは、indexが0の写真データ)。