> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # パッシブライブネス検知API：ディープフェイク検出 > DiditのパッシブライブネスAPIは、1枚の画像からマスク、印刷物、リプレイ、ディープフェイクを検知します。完全パッシブで推論は2秒未満、従量課金制で月額最低料金はありません。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/passive-liveness/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 本人確認API。x-api-keyヘッダーで認証します。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/passive-liveness/: post: tags: - Standalone APIs summary: パッシブライブネス description: >- 単一の顔画像から、プレゼンテーション攻撃（印刷された写真、画面の再生、マスク、ディープフェイク）を検知します。動画、動作、ユーザー操作は不要です。 **仕組み。** 画像は生体認証モデルで分析され、検出された顔のうち最も大きいものが評価され、ライブネスの`score`（0〜100）が算出されます。`error`重大度の警告が1つでも発生すると、`status`は`Declined`になります： - `NO_FACE_DETECTED`：ライブネスモデルが顔を検出できなかった - `LOW_LIVENESS_SCORE`：スコアが`face_liveness_score_decline_threshold`（デフォルトは`30`）以下 - `LIVENESS_FACE_ATTACK`：モデルがプレゼンテーション攻撃を検知した - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`：顔が顔ブロックリストのエントリと一致した `MULTIPLE_FACES_DETECTED`は`warning`重大度のシグナルです（却下にはなりません）。`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`は、同じ顔が別の承認済みセッションにすでに登場していることを示す`information`重大度のシグナルです（却下になることはありません）。`face_quality`と`face_luminance`（0〜100、null許容）は撮影品質を表します。 **ブロックリストと重複のスクリーニング。** `save_api_request`の有無にかかわらず、**すべての**呼び出しで実行され、検出された顔をアプリケーションの顔検索インデックスと照合します。同じ`vendor_data`を持つ過去の顔はインデックス検索全体から除外されます。そのため、同じユーザーに対してライブネスを再実行しても`DUPLICATED_FACE`はトリガーされません。また、呼び出し元自身の`vendor_data`を持つセッションに由来するブロックリスト登録済みの顔もフラグ付けされません（同じ`vendor_data`の顔については`FACE_IN_BLOCKLIST`のスクリーニングがスキップされます）。 **請求。** `200`レスポンス1件ごとに、Passive Liveness APIのクレジットを1つ消費します（プランのクレジットまたはチャージ残高から支払われます）。残高が不足している場合は、画像処理の前に`403`が返されます。 **セッションの保存と顔の登録（`save_api_request`、デフォルトは`true`）。** `true`の場合、呼び出しはAPIタイプのセッションとして保存され（Business Console、返された`request_id`を使った`GET /v3/session/{sessionId}/decision/`、`status.updated`のWebhook）、参照画像と顔の切り抜きが保存され、検出された顔が**顔検索インデックスに登録**されます。これにより、以降の顔検索の呼び出しや重複チェックでこの顔を照合できます。`false`の場合、呼び出しは1回限りで、何も保存されず、顔も登録されません（ブロックリストと重複のスクリーニングは引き続き実行されます）。 **サンドボックス。** サンドボックスのAPIキーでは、すべての処理と請求がスキップされます。リクエストの検証後（不正な入力には引き続き`400`が返されます）、エンドポイントは固定の`Approved`モックペイロードを返します。セッションは保存されず、クレジットも消費されません。 **認証。** アプリケーションのAPIキーを`x-api-key`ヘッダーで送信してください。認証情報がない、または無効な場合は`403`（`{"detail": "You do not have permission to perform this action."}`）が返されます。このAPIが`401`を返すことはありません。 **レート制限。** すべてのPOST/PATCH/DELETEエンドポイントで共有される書き込み枠として、APIキーごとに毎分300リクエストまでです。超過すると`429`が返されます。 operationId: post_v3passive-liveness parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- 正面を向いた顔画像（セルフィーなど）。使用可能な拡張子: `tiff`、`jpg`、`jpeg`、`png`、`webp`。最大アップロードサイズ: **5 MB**（これを超えるファイルは`400`で拒否されます）。画像は処理前に自動的に約0.5 MBに圧縮されるため、解像度を非常に高くしても精度は向上しません。画像には被写体を1人だけ含めてください。複数の顔が含まれる場合は最も大きい顔が評価され、`MULTIPLE_FACES_DETECTED`警告が追加されます。 face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- ライブネススコアのしきい値（0–100）。算出されたスコアがこの値**以下**の場合、`LOW_LIVENESS_SCORE`警告が出され、`status`が`Declined`に設定されます。デフォルトは`30`です。より厳格ななりすまし対策にするには値を上げてください。0–100の範囲外の値は`400`を返します。 example: 30 rotate_image: type: boolean default: false description: >- `true`の場合、入力を90度ずつ回転させて試し、最も良好に顔を検出できる向きを使用します。EXIFの向き情報がない場合に便利です。レイテンシが増加します。 example: false save_api_request: type: boolean default: true description: >- `true`（デフォルト）の場合、呼び出しをAPIタイプのセッションとして保存し、顔画像を保存し、`status.updated`Webhookを送信し、検出された顔を顔検索インデックスに登録します。`false`の場合、呼び出しは1回限りで、何も保存されず、顔も登録されません。ブロックリストと重複のスクリーニングは、どちらの場合も実行されます。 example: true vendor_data: type: string description: >- 任意の不透明な識別子（ユーザーID、メールアドレス、UUIDなど）です。保存されたセッションに格納され、そのまま返されます。また、同じ`vendor_data`を持つ過去のセッションを重複顔チェックから除外するためにも使用されるため、同じユーザーを再検証しても`DUPLICATED_FACE`は発生しません。 example: user-123 metadata: type: object additionalProperties: true description: >- セッションとともに保存され（`save_api_request=true`の場合）、そのまま返される任意のJSONオブジェクトです。マルチパートリクエストでは、JSONエンコードされた文字列フィールドとして送信してください。オブジェクトとして解析されます。 example: flow: withdrawal example: user_image: (binary JPEG/PNG selfie) face_liveness_score_decline_threshold: 30 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: withdrawal responses: '200': description: >- パッシブライブネスが完了しました。`liveness.score`は、画像に生身の人物が写っていることに対するモデルの0〜100の信頼度です。`error`重大度の警告が発生しない限り、`status`は`Approved`です。なりすましの顔やブロックリストに登録された顔でも`200`が返るため、HTTPコードだけでなく`liveness.status`と`liveness.warnings`を確認してください。`save_api_request=true`の場合、`request_id`は保存されたセッションIDです。 content: application/json: examples: Approved: summary: 実在する顔（警告なし） value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef liveness: status: Approved method: PASSIVE score: 95 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 warnings: [] face_quality: 84.21 face_luminance: 50.33 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - presentation attack: summary: モデルがなりすまし(印刷物、リプレイ、マスクなど)を検出しました value: request_id: f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c liveness: status: Declined method: PASSIVE score: 12.5 user_image: entities: - bbox: - 100 - 120 - 420 - 540 confidence: 0.81 age: 30.1 gender: female race: null best_angle: 0 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. - risk: LIVENESS_FACE_ATTACK feature: LIVENESS additional_data: null log_type: error short_description: Liveness Face Attack long_description: >- The system detected a potential attempt to bypass the liveness check. face_quality: 72.4 face_luminance: 48.2 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - face on blocklist: summary: 実在する顔だが、ブロックリストのエントリと一致 value: request_id: 0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e liveness: status: Declined method: PASSIVE score: 93.75 user_image: entities: - bbox: - 40 - 40 - 100 - 100 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 3242 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. face_quality: null face_luminance: null vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- `save_api_request=true`の場合は保存されたセッションID(`GET /v3/session/{sessionId}/decision/`で使用可能)、それ以外の場合は一時的な相関UUIDです。 liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- 重大度が`error`の警告が1つ以上発生した場合（顔が検出されない、スコアが低い、プレゼンテーション攻撃、ブロックリストへの該当）は`Declined`、それ以外は`Approved`です。`warning`/`information`のエントリ（複数の顔、重複）は、それだけで却下になることはありません。 method: type: string enum: - PASSIVE description: このエンドポイントでは常に`PASSIVE`です。 score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- 画像がなりすましではなく実在の人物を写していることを示すライブネスの信頼度（0–100、小数点以下2桁）。モデルが信頼度を返さなかった場合は`null`です。 example: 95 user_image: type: object description: 送信された画像の顔検出結果。 properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- 処理済み画像内で検出された顔のバウンディングボックス。`[x_min, y_min, x_max, y_max]`のピクセル座標で示します。 example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: 顔検出の信頼度（0～1）。 example: 0.732973 age: type: number format: float description: >- 検出された顔についてモデルが推定した年齢（歳）。参考情報であり、ライブネス検知の判定には影響しません。 example: 26.91 gender: type: string description: >- 検出された顔についてモデルが予測した性別（`male`または`female`）。参考情報です。 example: male race: type: string nullable: true description: 予約済みフィールドです。このエンドポイントのレスポンスでは常に`null`です。 example: null description: 検出された顔ごとに1エントリー。最も大きい顔が評価対象です。 best_angle: type: integer nullable: true description: >- 最も良好な顔検出結果が得られた回転角度(度)。`rotate_image=true`によって向きが補正された場合にのみゼロ以外になります。 example: 0 warnings: type: array description: >- リスクシグナル。重大度`error`(却下): `NO_FACE_DETECTED`、`LOW_LIVENESS_SCORE`(スコアがしきい値以下)、`LIVENESS_FACE_ATTACK`、`FACE_IN_BLOCKLIST`、`POSSIBLE_FACE_IN_BLOCKLIST`。重大度`warning`(レビュー対象、却下なし): `MULTIPLE_FACES_DETECTED`。重大度`information`(却下なし): `DUPLICATED_FACE`、`POSSIBLE_DUPLICATED_FACE`。同じ顔が別の承認済みセッションですでに検出されています。 items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: 機械可読なリスクコードです。 feature: type: string enum: - LIVENESS description: 警告を発生させた機能。このエンドポイントでは常に`LIVENESS`です。 additional_data: type: object nullable: true additionalProperties: true description: >- ほとんどの警告では`null`です。ブロックリストへのヒットには`{blocklisted_session_id, blocklisted_session_number, api_service}`が、重複へのヒットには一致したセッションを指す`{duplicated_session_id, duplicated_session_number, api_service}`が含まれます。 log_type: type: string enum: - error - warning - information description: >- 重大度。`error`の警告は`status`を`Declined`にします。`warning`と`information`のエントリーは参考情報であり、それ単独で却下になることはありません。 short_description: type: string description: リスクを人が読める形で1行にまとめた要約。 long_description: type: string description: リスクを人が読める形で説明したもの。 face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- 検出された顔の撮影品質スコア（0〜100に正規化）。モデルが信頼できる値を算出できなかった場合は`null`です。 example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: 検出された顔の明るさ。0–100に正規化されています。利用できない場合は`null`です。 example: 50.33 vendor_data: type: string nullable: true description: 送信した`vendor_data`のエコー、または`null`。 metadata: type: object nullable: true additionalProperties: true description: 送信した`metadata`オブジェクトのエコー、または`null`。 created_at: type: string format: date-time description: >- レスポンスが生成された日時を示すISO 8601タイムスタンプ（UTC）。例: `2026-06-12T01:04:42.763237+00:00`。 '400': description: >- バリデーションエラー。`user_image`がない、5MBを超える、サポートされていない拡張子である、サーバー側で画像のデコードに失敗した、またはオプションが範囲外の場合に返されます。フィールドエラーはDRFの`{field: [messages]}`エンベロープを使用し、画像デコードの失敗は`{"error": ...}`を使用します。 content: application/json: examples: Missing image: summary: フォームデータに`user_image`が含まれていません value: user_image: - No file was submitted. Invalid image format: summary: 許可された拡張子だが、画像の内容をデコードできない value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: ファイル拡張子がtiff/jpg/jpeg/png/webp以外 value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: アップロードが5MBの上限を超えています value: user_image: - File size should not exceed 5 MB '403': description: >- 権限がありません。`x-api-key`ヘッダーがない場合に加え、呼び出し元の組織の残高が呼び出しを賄えない場合にも返されます。誤った、取り消された、または期限切れのキーの場合は`401`が返されます。キーがない場合は`{"detail": ...}`とともに`403`が返され、誤った、取り消された、または期限切れのキーの場合は`401`が返されます。クレジット不足の場合は、画像の処理が行われる前に`{"error": ...}`とともに`403`が返されます。 content: application/json: examples: Missing or invalid API key: summary: '`x-api-key`ヘッダーがないか、キーが無効または失効しています' value: detail: You do not have permission to perform this action. Not enough credits: summary: 組織の残高でこの呼び出しの料金を賄えません value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- レート制限を超過しました。すべてのPOST/PATCH/DELETEエンドポイントは、APIキーごとに1分あたり300件の書き込みリクエストという共通の上限を共有します。レスポンスには`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`、`Retry-After`ヘッダーが含まれます。 content: application/json: examples: Write rate limit exceeded: summary: 現在の1分間に300件を超える書き込みリクエスト value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'face_liveness_score_decline_threshold=30' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.passive_liveness.check( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "withdrawal"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.passiveLiveness.check({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"withdrawal\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.PassiveLivenessCheckParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "withdrawal")) .build()); System.out.println(result); - lang: php label: PHP source: |- passiveLiveness->check([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'withdrawal'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.passive_liveness.check( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "withdrawal" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.