FACEIO REST API

非公開バックエンドからFACEIO REST APIを呼び出し、Facial IDの管理、顔画像の比較、年齢と性別の推定、payloadとPIN Codeの更新、アプリケーション統計とAPIステータスの取得を行います。

FACEIO Consoleを開く

FACEIO Consoleでアプリケーションを作成し、Application Managerから非公開APIキーを取得します。APIキーはバックエンドだけで管理してください。

FACEIO REST API

Facial ID管理、顔認証、アプリケーション操作のためのバックエンドHTTPエンドポイント

FACEIOアプリケーションにはAPIキーが自動的に割り当てられます。このキーは、FACEIO Console ↗のApplication Managerから取得できます。この非公開APIキーを使うと、HTTPSをサポートする任意のプログラミング言語から、バックエンドでFACEIO REST APIを呼び出せます。

  • パラメータの受け渡しとAPIキー認証には標準のHTTP機能を使用します。
  • 成功状態とエラー状態を示す標準HTTPレスポンスコードを返します。
  • すべてのリクエストで、処理結果にかかわらずJSONを返します。

重要なお知らせ

API 呼び出しと fio.js JavaScript ライブラリのインスタンス化は、別のワークフローです。登録と認証はユーザーのブラウザー上で行われます。REST API 呼び出しはアプリケーションの非公開バックエンドから行い、プランに応じてクォータやスロットリングの対象となる場合があります。FACEIO を初めて利用する場合は、まずスタートガイド、次に統合ガイドを確認してください。REST API のクォータ制限は料金表で確認できます。

REST APIベースURL

  • FACEIO APIのベースエンドポイントは https://api.faceio.net/です。
  • リクエストURLの形式はhttps://api.faceio.net/cmd?param=val&param2=val2です。cmdはAPIエンドポイント、param=valはそのパラメータを表します。各エンドポイントのセクションに対応するHTTPメソッドを記載しています。
  • APIの稼働状況は、status.faceio.net ↗でリアルタイムに確認できます。
API概要
ベースURL api.faceio.net
ヘルスチェックエンドポイント api.faceio.net/status ↗
アーキテクチャ RESTful
HTTPおよびTLSバージョン HTTP/1.1、HTTP/2、HTTP/3、TLS 1.2および1.3
認証 キー方式 ↓
ネットワーク Cloudflare
HTTPレスポンスMIMEタイプ application/json
HTTPステータスコード 以下を参照 ↓

APIキーを取得する

新しいFACEIOアプリケーションを作成すると APIキーが自動的に割り当てられます。次の手順でキーを取得・管理できます：

  1. 1 FACEIO Console ↗にログインします。
  2. 2 Application Managerを開きます。
  3. 3 管理するアプリケーションを選択します。
  4. 4 APIキータブを開きます。
  5. ✓ サーバー側のHTTP API呼び出しに使用するAPIキーをコピーします。同じタブでAPI統計とクォータ情報も確認できます。

認証

対象のFACEIO APIエンドポイントへ送信するHTTPリクエストにAPIキーを含めて認証します。APIキーの取得と管理については上のセクションを確認してください。

認証方法

次のいずれかの方法でAPIキーを送信します。

HTTPヘッダー

APIキーを WWW-Authenticate HTTPヘッダーに埋め込みます：

WWW-Authenticate: Bearer API_KEY
クエリパラメータ

またはキーを POST または GET リクエストURLに追加します：

https://api.faceio.net/endpoint?param=val&key=API_KEY

セキュリティ警告： APIキーを安全に管理してください。クライアント側コード、公開リポジトリ、ブラウザJavaScript、モバイルアプリのバンドル、ログ、分析ツールに決して公開しないでください。認証済みのサーバーサイドスクリプトのみを使用し、本番利用前にセキュリティのベストプラクティスガイドを確認してください。

HTTPレスポンス、ステータス、エラーコード

各リクエストでは次のHTTPステータスコードが返されます。すべてのAPIエンドポイントは、成功・失敗にかかわらずapplication/jsonを返します。ユーザーレコードの更新などを行う前に、バックエンドでエラーを明示的に処理してください。

200 成功。APIエンドポイントが操作を正常に実行しました。
400 不正なリクエスト。通常は必須パラメータが不足しています。
401 認証されていません。APIキーがないか無効です。
404 見つかりません。リクエストされた項目（例：Facial ID）は存在しません。
405 メソッドが許可されていません。このエンドポイントではそのHTTPメソッドを扱いません。
429 リクエストが多すぎます。レート制限を超えました。料金表でクォータ制限を確認してください。
500 サーバーエラー。サーバー側のエラーまたはメンテナンスです。必要に応じてお知らせします。

エンドポイントドキュメント

DELETEFACIALID

GET
エンドポイントアクセスURL https://api.faceio.net/deletefacialid
説明

Facial IDと関連するpayloadデータをFACEIOアプリケーションから削除します。この操作により、選択した顔認識エンジンへ関連する生体認証ハッシュの消去も指示されます。

Facial ID は、登録済みユーザーごとに匿名で割り当てられる一意の識別子（UUID）です。登録は、クライアント側ライブラリ fio.js の enroll() メソッドで行います。

利用可能プラン 全プラン
HTTPメソッド GET

HTTPパラメータ

フィールド 型 必須 説明
key HEX String はい アプリケーションのREST APIキー。
fid String はい 完全に削除するFacial IDを指定します。

HTTPレスポンス

application/json

このAPIエンドポイントは常にJSONオブジェクトを返します。次のフィールドが返されます：

フィールド 型 説明
status Integer 標準HTTPステータスコードです。成功時は200、それ以外は401などのエラーステータスを返します。
payload Boolean Facial IDとデータが正常に完全消去された場合はTRUE、それ以外の場合はFALSEです。
Facial ID削除コード例（Python）

CHECKFACIALID

GET
エンドポイントアクセスURL https://api.faceio.net/checkfacialid
説明

指定したFacial IDが、APIキーに関連付けられたFACEIOアプリケーションに登録されているか確認します。
利用可能プラン 有料プランで利用できます。 詳しくは料金ページをご覧ください。
HTTPメソッド GET

HTTPパラメータ

フィールド 型 必須 説明
key HEX String はい アプリケーションのREST APIキー。
fid String はい 登録状況を確認するFacial IDを指定します。

HTTPレスポンス

application/json

このAPIエンドポイントは常にJSONオブジェクトを返します。次のフィールドが返されます：

フィールド 型 説明
status Integer 標準HTTPステータスコードです。成功時は200、それ以外はエラーステータスを返します。
valid Boolean Facial IDが登録済みの場合はTRUE、それ以外の場合はFALSEです。
Facial ID検証コード例（Python）

FACE-VERIFY

POST
エンドポイントアクセスURL https://api.faceio.net/faceverify
説明

2つの顔画像を比較

faceverifyエンドポイントは2枚の画像内の顔を比較し、一致結果と類似度スコアを返します。

Source画像とTarget画像を、それぞれ1人の顔だけが含まれる状態で送信します。FACEIOへの事前登録は不要です。返されたスコアの扱いはバックエンド側で決定してください。

プライバシーに関する注意： 処理はメモリ（RAM）上で行われます。画像は分析直後に削除され、データは記録・保存されません。顔照合を本番ワークフローに追加する前に、プライバシーのベストプラクティスを確認してください。
利用可能プラン 有料プランで利用できます。 詳しくは料金ページをご覧ください。
HTTPメソッド POST

HTTPパラメータ

フィールド 型 必須 説明
key HEX String はい アプリケーションのREST APIキー。
src Base64 | URL はい 照合元の人物の画像です。Base64 エンコード文字列（data URI 形式）または公開 URL を指定してください。画像には比較対象となる 1 人の顔だけを含めてください。
target Base64 | URL はい 照合先の人物の画像です。照合元と比較する画像を、Base64 エンコード文字列（data URI 形式）または公開 URL で指定してください。

HTTPレスポンス

application/json

このAPIエンドポイントは常にJSONオブジェクトを返します。次のフィールドが返されます：

フィールド 型 説明
status Integer 標準HTTPステータスコードです。成功時は200、それ以外はエラーステータスを返します。
same_person Boolean SourceとTargetの顔が同一人物と判定された場合はTRUE、それ以外の場合はFALSEです。
dist Float 0から1の距離類似度スコア。1に近いほど同一人物である可能性が高いことを示します。
sim Float コサイン類似度スコア（0から1）。1に近いほど類似度が高いことを示します。
Face Verifyコード例（Python）

AGE-CHECK

POST
エンドポイントアクセスURL https://api.faceio.net/agecheck
説明

年齢と性別の推定

agecheckエンドポイントは、画像内の顔から年齢と性別の推定値を返します。FACEIOへの事前登録は不要です。年齢は概算値であり、本人確認、正確な年齢、法的な適格性判断の証明には使用しないでください。

プライバシーに関する注意：処理はメモリ（RAM）上で行われます。画像は分析直後に削除され、データは記録・保存されません。年齢と性別の推定を本番環境へ追加する前に、プライバシーのベストプラクティスを確認してください。
利用可能プラン 有料プランで利用できます。 詳しくは料金ページをご覧ください。
HTTPメソッド POST

HTTPパラメータ

フィールド 型 必須 説明
key HEX String はい アプリケーションのREST APIキー。
img Base64 | URL はい 分析する顔を含む入力画像。形式： data:{MIME_type};base64,{data} または公開URL。

HTTPレスポンス

application/json

このAPIエンドポイントは常にJSONオブジェクトを返します。次のフィールドが返されます：

フィールド 型 説明
status Integer 標準HTTPステータスコードです。成功時は200、それ以外はエラーステータスを返します。
age Integer 画像内の人物の推定年齢。
gender String 画像内の人物の性別推定。
年齢と性別の推定コード例（Python）

SETFACIALIDPAYLOAD

POST
エンドポイントアクセスURL https://api.faceio.net/setfacialidpayload
説明

特定の登録済みユーザーの Facial ID に関連付けられたペイロードデータを設定または変更します。

保存されたpayloadは、次回の認証成功後にfio.jsを通じてWebサイトまたはWebアプリへ返されます。内部ユーザーIDなど、必要最小限のアプリケーションデータに使用してください。秘密情報や認可判断をpayloadに含めないでください。
利用可能プラン 有料プランで利用できます。 詳しくは料金ページをご覧ください。
HTTPメソッド POST

HTTPパラメータ

フィールド 型 必須 説明
key HEX String はい アプリケーションのREST APIキー。
fid String はい payloadを更新するFacial IDを指定します。
payload 文字列／生データ はい Facial IDに関連付ける新しいペイロードデータ。今後の認証時に返されます。文字列、JSON、その他バックエンドで管理する形式を使用できます。

HTTPレスポンス

application/json
フィールド 型 説明
status Integer 標準HTTPステータスコードです。成功時は200、それ以外はエラーステータスを返します。
payload Boolean payloadが正常に更新された場合はTRUE、それ以外の場合はFALSEです。

SETFACIALIDPINCODE

POST
エンドポイントアクセスURL https://api.faceio.net/setfacialidpincode
説明

FACEIO アプリケーションに登録された特定のユーザーに関連付けられた PIN コードを設定または変更します。
利用可能プラン 有料プランで利用できます。 詳しくは料金ページをご覧ください。
HTTPメソッド POST

HTTPパラメータ

フィールド 型 必須 説明
key HEX String はい アプリケーションのREST APIキー。
fid String はい PIN Codeを更新するFacial IDを指定します。
pin Number はい Facial IDに関連付ける新しいPINコード。今後の認証で求められた際にユーザーが確認します。PINは4桁以上16桁以下で指定してください。

HTTPレスポンス

application/json

このAPIエンドポイントは常にJSONオブジェクトを返します。次のフィールドが返されます：

フィールド 型 説明
status Integer 標準HTTPステータスコード。 200 成功を示します。
payload Boolean PIN Codeが正常に更新された場合はTRUE、それ以外の場合はFALSEです。
PIN変更コード例（Python）

STAT

GET
エンドポイントアクセスURL https://api.faceio.net/stat
説明

FACEIO アプリケーションの分析と統計を取得します。インデックス済みの顔の総数、API 呼び出し数、最近の登録などが含まれます。統計はキャッシュされ、5 分ごとに更新されます。
利用可能プラン 有料プランで利用できます。 詳しくは料金ページをご覧ください。
HTTPメソッド GET

HTTPパラメータ

フィールド 型 必須 説明
key HEX String はい アプリケーションのREST APIキー。

HTTPレスポンス

application/json

このAPIエンドポイントは常にJSONオブジェクトを返します。次のフィールドが返されます：

フィールド 型 説明
status Integer 標準HTTPステータスコードです。成功時は200、それ以外は401などのエラーステータスを返します。
total_api_calls Integer このアプリケーションが行ったAPI呼び出しの累計。
total_indexed_faces Integer 現在登録またはインデックスされている一意の顔の総数。
last_indexed_faces Array 最近登録されたユーザーのFacial ID一覧。

ABOUT

GET
エンドポイントアクセスURL https://api.faceio.net/about
説明

実行中のFACEIO APIインスタンスのバージョン情報と著作権表示を取得します。
利用可能プラン 全プラン
HTTPメソッド GET

HTTPパラメータ

パラメータは不要です。

HTTPレスポンス

application/json
フィールド 型 説明
status Integer 標準HTTPステータスコードです。成功時は200、それ以外はエラーステータスを返します。
payload String サーバーバージョン文字列と著作権表示。

STATUS

GET
エンドポイントアクセスURL https://api.faceio.net/status
説明

FACEIO APIサーバーの稼働状態を確認します。リアルタイムのステータス履歴はstatus.faceio.net ↗で確認できます。
利用可能プラン 全プラン
HTTPメソッド GET

HTTPパラメータ

パラメータは不要です。

HTTPレスポンス

application/json
フィールド 型 説明
status Integer 200 稼働状態（System OK）を示します。 500 メンテナンスまたはサービス停止を示します。
error String ステータスが200以外の場合のエラーメッセージ。
payload String ステータスメッセージ（例："System OK"）。

バックエンドをREST APIに接続する

FACEIOアプリケーションを作成し、Consoleから非公開REST APIキーを取得して、バックエンドからドキュメント記載のエンドポイントを呼び出します。APIキーをブラウザーやモバイルクライアントのコードに公開しないでください。

はじめにを読む → FACEIO Consoleを開く
99.7% LFW精度