なりすまし判定 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 が返ります

一時的にサービスが利用できない状態です。少し時間をおいて再試行してください。継続する場合は サポート窓口 までご連絡ください。

サポート窓口

お探しの情報が見つからない場合は、下記までご連絡ください。

お問い合わせの際、次の情報を添えていただけると調査がスムーズです。

• ご登録のメールアドレス（または AWS Account ID）
• 発生日時（タイムゾーンを明記してください）
• 使用した API キーの先頭プレフィックス（lc_a1B2c…）
• レスポンスの metadata.date と error.code

⚠️ API キーの全文は絶対に送信しないでください。 調査には先頭プレフィックスだけで十分です。誤って送信してしまった場合は、ダッシュボードの Regenerate で直ちにキーを再生成してください（顧客管理画面ガイド）。