Liveness Detection API

なりすまし判定 API FAQ・トラブルシューティング

よくあるご質問と、エラー発生時の対処方法をまとめています。API の使い方はクイックスタートガイド、各エンドポイントの詳細は API リファレンスをご覧ください。

基本

なりすまし判定 API は何を判定しますか？

送信された顔画像が、実物の顔か、写真・スマホ画面などに映った偽物（なりすまし）かを判定します。結果は isFakeFace（偽物疑いの真偽）と isFakeLikelihood（0.0〜1.0 のスコア）で返ります。本人確認（顔認証）そのものは行いません。

顔認証や eKYC も提供していますか？

いいえ。本 API は、顔認証の前後に組み合わせて使う「なりすまし判定」の要素技術を提供します。顔認証エンジンや eKYC サービスはお客様側でご用意いただき、本 API と組み合わせてご利用ください。

動画やアクション判定（指示した動作の検出）に対応していますか？

本 API（POST /v1/check/liveness）は、単一の静止画によるフェイク判定に対応しています。動画ベースのアクション判定が必要な場合は、SDK のご利用をご検討ください（お問い合わせください）。

スマートフォンのカメラ画像でも使えますか？

はい。特別なカメラは不要で、スマートフォン搭載カメラで撮影した画像でもご利用いただけます。

認証・API キー

`401 invalid_api_key` が返ります

次の点をご確認ください。

X-API-Key ヘッダーにキー全文（lc_ で始まる文字列）を正しく設定しているか
キーが無効化・再生成されていないか（再生成すると旧キーは即時失効します）
ダッシュボードの「API キー」画面で、有効なキーかどうか

API キーはどこで取得しますか？

アカウント有効化直後の画面に Primary / Secondary の2キーが全文表示されます（全文が表示されるのはこの1回だけです）。控え忘れた場合は、顧客ダッシュボード（https://liveness.api.pas-ta.io/console/dashboard）の Regenerate で新しいキーを発行してください（旧キーは即時無効化され、新キーはその場で1回だけ表示されます）。

キーが漏れてしまった場合は？

Secondary キーへ切り替えてサービスを継続したまま、Primary を再生成できます（無停止ローテーション）。手順はクイックスタートガイドを参照してください。

リクエスト・画像

`400 invalid_image` が返ります

画像のデコードに失敗したか、顔が検出できなかった場合に発生します。

対応フォーマットは jpeg / png のみ、サイズ上限は 10MB です
image_format が実際の画像形式と一致しているか確認してください
顔が正面を向き、十分な明るさ・解像度で写っているか確認してください（→ 画像入力ガイドライン）

`400 invalid_request` が返ります

リクエストボディの形式エラーです。image（Base64 文字列）と image_format（"jpeg" または "png"）が正しく含まれているかご確認ください。

画像はどのように送ればよいですか？

画像を Base64 エンコードし、{"image": "...", "image_format": "jpeg"} の JSON で POST /v1/check/liveness に送信します。サンプルコード（curl / Python / Node.js）は API リファレンスを参照してください。

レート制限・使用量

`429 quota_exceeded` が返ります

月間コール数の上限に達し、かつ API 停止モードのときに発生します。

当月の使用量は GET /v1/usage で確認できます
継続利用するには、ダッシュボードでハードキャップを OFF（超過従量で継続）にするか、上位プランへアップグレードしてください
free プランは超過課金ができないため、上限到達時は常に 429 になります

上限を超えたらどうなりますか？

デフォルト（ハードキャップ OFF）では、上限超過後も判定を継続し、超過分は従量課金されます。ハードキャップ ON の場合は上限で停止（429）します。挙動はダッシュボードからいつでも切り替えられます。

クレジットは翌月に繰り越せますか？

いいえ。月初に付与されたクレジットは当月限りで、翌月へは繰り越されません（月次境界は UTC 基準です）。

判定結果の解釈

「なりすましかどうか」の最終判定はどう行いますか？

isFakeFace（true = 偽物疑い）と isFakeLikelihood（0.0〜1.0 のスコア）を、お客様の用途に応じたしきい値で評価してください。API は固定の合否（result）を返しません。しきい値を調整することで、誤検知（False Positive）と見逃し（False Negative）のバランスを最適化できます。

レスポンスに判定画像が含まれないのはなぜですか？

レスポンスサイズを抑えるため、画像データは返しません。判定に必要な数値（isFakeFace / isFakeLikelihood / 顔矩形など）のみを返します。

性能・運用

1回の判定にかかる時間はどれくらいですか？

推論自体はおおよそ数百ミリ秒です（レスポンスの latency_ms で確認できます）。ネットワーク往復を含む実際の応答時間は、ご利用環境や画像サイズによって変動します。

対応している開発言語・OS は？

HTTPS でリクエストを送れる環境であれば、言語・OS を問わずご利用いただけます。サンプルコード（curl / Python / Node.js）は API リファレンスを参照してください。

`503 service_unavailable` が返ります

一時的にサービスが利用できない状態です。少し時間をおいて再試行してください。継続する場合はお問い合わせください。

お探しの情報が見つからない場合は、お問い合わせフォームよりご連絡ください。