> ## 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のPOST /v3/age-estimation/は、パッシブライブネス検知を内蔵したAI年齢推定APIです。身分証は不要で、推論は2秒未満、料金は従量課金制です。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/age-estimation/ 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/age-estimation/: post: tags: - Standalone APIs summary: 年齢推定（顔の年齢+パッシブライブネス） description: >- 1枚の顔写真から人物の年齢を推定し、同じ呼び出しでパッシブライブネスチェックを実行します。モデルが予測した`age_estimation`(年単位)、ライブネスの`score`(0〜100)、および`Approved`/`Declined`の`status`を返します。年齢は**顔からモデルが予測したものであり、書類と照合して検証されたものではありません**。年齢制限や負担の少ないチェックに使用し、法的な年齢証明としては使用しないでください。 **仕組み。** 画像内の顔が解析されます(撮影画像が横向きや上下逆になる可能性がある場合は`rotate_image=true`を設定してください)。検出された各顔に推定年齢が付与され、フレーム内で最も大きい顔が`age_estimation`の値になります。並行して、パッシブライブネスモデルが写真に写っているのが生身の人物かどうかをスコア化し(ユーザーへのチャレンジは不要)、プレゼンテーション攻撃(写真の写真、画面、マスク)を検出します。最良の結果を得るには、1枚の画像につき、正面を向いた明るく鮮明な顔を1つ送信してください。 **判定ロジック。** 警告が1つでもあれば却下されます。`status`が`Approved`になるのは、`warnings`配列が空の場合のみです。ライブネスの`score`が`face_liveness_score_decline_threshold`(デフォルト`30`)以下の場合は`LOW_LIVENESS_SCORE`が追加されます。攻撃が検出された場合は`LIVENESS_FACE_ATTACK`、ライブネスモデルが顔を検出できなかった場合は`NO_FACE_DETECTED`、顔の年齢を推定できなかった場合は`AGE_NOT_DETECTED`(`age_estimation`は`null`)、推定年齢が`age_estimation_decline_threshold`(デフォルト`18`)未満の場合は`AGE_BELOW_MINIMUM`が追加されます。しきい値に近い境界的な年齢については、書類に基づく検証へのフォールバックを用意してください。しきい値付近の顔ではモデルの誤差が大きくなります。 **請求。** `200`レスポンスごとに年齢推定APIのクレジットを1つ消費します(プランのクレジットまたはチャージ残高から支払われます)。組織の残高で呼び出しをまかなえない場合、エンドポイントは画像処理を行う前に、クレジット不足エラーとともに`403`を返します。 **セッションの保存(`save_api_request`、デフォルト`true`)。** `true`の場合、呼び出しはAPIタイプのセッションとして保存されます。Business Consoleに表示され、返される`request_id`は`GET /v3/session/{sessionId}/decision/`に渡せる実際のセッションIDになります(結果はそこで`liveness_checks[]`内に`features: ["AGE_ESTIMATION"]`とともに公開されます)。また、顔の切り抜き画像と参照画像が保存され、顔エンベディングがアプリケーションの顔インデックス(顔検索と重複検出に使用)に追加され、`status.updated`のWebhookが送信されます。`false`の場合は何も保存されず、`request_id`は後から参照できない一回限りの相関UUIDになります。 **サンドボックス。** サンドボックスのAPIキーでは、すべての処理と請求がスキップされます。リクエストの検証後(不正な入力の場合は引き続き`400`を返します)、エンドポイントは静的な`Approved`のモックペイロード(`age_estimation: 30`、警告なし)を返し、セッションは保存されず、クレジットも消費されません。 **認証。** アプリケーションの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_v3age-estimation parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- 分析する顔写真（例: セルフィー）。被写体の顔がはっきりと写り、十分に明るい正面向きの写真を1枚送信してください。使用可能な拡張子: `tiff`、`jpg`、`jpeg`、`png`、`webp`（PDFは不可）。最大アップロードサイズ: **5 MB**（これを超えるファイルは`400`で拒否されます）。画像は処理前に自動的に約0.3 MBに圧縮されるため、解像度を非常に高くしても精度は向上しません。 face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- ライブネスのしきい値（0–100）。ライブネスの`score`がこの値**以下**の場合、`LOW_LIVENESS_SCORE`警告が追加され、却下されます。より厳格ななりすまし対策にするには値を上げてください。0–100の範囲外の値は`400`を返します。 example: 30 age_estimation_decline_threshold: type: integer default: 18 minimum: 0 maximum: 100 description: >- 許容される推定年齢の最小値（歳）。推定年齢がこの値を**下回る**場合は`AGE_BELOW_MINIMUM`警告が追加され、却下されます。`0`に設定すると年齢チェックが無効になります（その場合、呼び出しではライブネス検知と年齢推定のみが実行され、年齢に基づく判定は行われません）。 example: 18 rotate_image: type: boolean default: false description: >- `true`の場合、入力画像を90度単位（0、90、180、270）で試し、最も良好に顔を検出できる向きを使用します。EXIFの向き情報がないモバイル撮影画像に便利です。レイテンシが増加するため、画像が正立していることを保証できない場合にのみ有効にしてください。 example: false save_api_request: type: boolean default: true description: >- `true`（デフォルト）の場合、呼び出しはAPIタイプのセッションとして保存されます。このセッションはBusiness Consoleに表示され、返された`request_id`を使って`GET /v3/session/{sessionId}/decision/`で取得でき、`status.updated`Webhookで通知され、検出された顔はアプリケーションの顔インデックスに追加されます。`false`の場合、何も保存されず、`request_id`はレスポンスの照合専用の一時的なUUIDになります。 example: true vendor_data: type: string description: >- 任意の不透明な文字列（社内のユーザーID、メールアドレス、UUIDなど）です。保存されたセッションに格納され、レスポンスでそのまま返されます。API呼び出しを自社の記録と関連付けたり、後でセッションを絞り込んだりするために使用します。 example: user-123 metadata: type: object additionalProperties: true description: >- セッションとともに保存され（`save_api_request=true`の場合）、レスポンスでそのまま返される任意のJSONオブジェクトです。マルチパートリクエストでは、JSONエンコードされた文字列フィールドとして送信してください（例: `metadata={"flow":"age-gate"}`）。オブジェクトとして解析されます。 example: flow: age-gate example: user_image: (binary JPEG/PNG of the selfie) face_liveness_score_decline_threshold: 30 age_estimation_decline_threshold: 18 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: age-gate responses: '200': description: >- 年齢推定とパッシブライブネスが完了しました。`age_estimation.age_estimation`は、検出された最も大きい顔についてモデルが予測した年齢（年）です（顔がない場合は`null`）。`age_estimation.score`はパッシブライブネスのスコア（0–100）です。`status`は`warnings`が空の場合にのみ`Approved`になります。未成年またはなりすましの撮影でも`200`と`status: "Declined"`が返されるため、HTTPコードだけでなくボディを確認してください。`save_api_request=true`の場合、`request_id`は保存されたセッションIDです。 content: application/json: examples: Approved: summary: 実在する成人の顔（両方のチェックに合格） value: request_id: 0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1 age_estimation: status: Approved method: PASSIVE score: 97.5 user_image: entities: - age: 27.33 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 27.33 warnings: [] vendor_data: user-123 metadata: flow: age-gate created_at: '2026-06-12T02:24:11.512941+00:00' Declined - age below threshold: summary: 推定年齢が`age_estimation_decline_threshold`未満 value: request_id: 9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2 age_estimation: status: Declined method: PASSIVE score: 95 user_image: entities: - age: 16.5 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: female best_angle: 0 age_estimation: 16.5 warnings: - risk: AGE_BELOW_MINIMUM feature: LIVENESS additional_data: null log_type: error short_description: Age below minimum long_description: >- The age of the face is below the minimum age threshold for the application. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:26:40.118332+00:00' Declined - liveness too low: summary: ライブネススコアが却下のしきい値以下（なりすましの可能性） value: request_id: 5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77 age_estimation: status: Declined method: PASSIVE score: 5 user_image: entities: - age: 25 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 25 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. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:02.901547+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- `save_api_request=true`の場合は保存されたセッションID(`GET /v3/session/{sessionId}/decision/`で使用可能)、それ以外の場合は一時的な相関UUIDです。 age_estimation: type: object properties: status: type: string enum: - Approved - Declined description: >- 警告が発生しなかった場合は`Approved`、それ以外の場合は`Declined`になります（このエンドポイントが生成する警告はすべて却下となります）。 method: type: string enum: - PASSIVE description: ライブネスの方式。このエンドポイントでは常に`PASSIVE`（単一画像、ユーザーへのチャレンジなし）です。 score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- 0から100のパッシブライブネススコアで、写真に生身の人物が写っていることに対するモデルの信頼度です。`face_liveness_score_decline_threshold`と比較され、その値以下の場合は`LOW_LIVENESS_SCORE`で却下されます。ライブネスモデルが信頼度を返さない場合は`null`になります。しきい値の比較ではnullが0として扱われるため、この場合も`LOW_LIVENESS_SCORE`で却下されます。 example: 97.5 user_image: type: object description: 分析した画像の顔検出結果。 properties: entities: type: array description: >- 検出された顔ごとに1エントリー。顔が見つからなかった場合は空です（その場合`age_estimation`は`null`となり、`AGE_NOT_DETECTED`警告が追加されます）。 items: type: object properties: age: type: number format: float description: この顔についてモデルが推定した年齢（歳）。 example: 27.33 bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- 処理済み画像内で検出された顔のバウンディングボックス。`[x_min, y_min, x_max, y_max]`のピクセル座標で示します。 example: - 40 - 40 - 100 - 100 confidence: type: number format: float minimum: 0 maximum: 1 description: 顔検出の信頼度（0～1）。 example: 0.7177750468254089 gender: type: string description: >- 検出された顔についてモデルが予測した性別（`male`または`female`）。参考情報です。 example: male best_angle: type: integer nullable: true description: >- 最も良好な顔検出結果が得られた回転角度(度: 0、90、180、270のいずれか)。`rotate_image=true`によって向きが補正された場合にのみゼロ以外になります。 example: 0 age_estimation: type: number format: float nullable: true description: >- 検出された顔のうち**最も大きい**顔についてモデルが予測した年齢（歳）。顔の年齢を推定できなかった場合は`null`になります（`AGE_NOT_DETECTED`警告が追加され、呼び出しは却下されます）。 example: 27.33 warnings: type: array description: 問題なく承認された場合は空です。エントリが1件でもあると`status`は`Declined`になります。 items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - AGE_NOT_DETECTED - AGE_BELOW_MINIMUM description: >- 機械可読なリスクコードです。`NO_FACE_DETECTED`：ライブネスモデルが顔を検出できませんでした。`LOW_LIVENESS_SCORE`：ライブネスの`score`が`face_liveness_score_decline_threshold`以下です。`LIVENESS_FACE_ATTACK`：プレゼンテーション攻撃（写真、画面、マスク）が検出されました。`AGE_NOT_DETECTED`：顔から年齢を推定できませんでした。`AGE_BELOW_MINIMUM`：推定年齢が`age_estimation_decline_threshold`を下回っています。`NO_FACE_DETECTED`と`LOW_LIVENESS_SCORE`は同時には発生しません。顔が検出されない場合は`NO_FACE_DETECTED`のみが出力されます。 feature: type: string enum: - LIVENESS description: 警告を発生させた機能。このエンドポイントでは常に`LIVENESS`です。 additional_data: type: object nullable: true additionalProperties: true description: 年齢推定の警告では常に`null`です。 log_type: type: string enum: - error description: >- 重大度。このエンドポイントが生成する警告はすべて`error`であり、`status`を`Declined`に設定します。 short_description: type: string description: リスクを人が読める形で1行にまとめた要約。 long_description: type: string description: リスクを人が読める形で説明したもの。 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）。 '400': description: >- バリデーションエラー。`user_image`がない、5MBを超える、サポートされていない拡張子である、またはしきい値が範囲外の場合に返されます。ボディはDRFの標準的なフィールドエラーエンベロープで、問題のあるフィールドごとにメッセージの配列が1つ含まれます。 content: application/json: examples: Missing user image: summary: フォームデータに`user_image`が含まれていません value: user_image: - No file was submitted. 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 Threshold out of range: summary: '`face_liveness_score_decline_threshold`が0–100の範囲外です' value: face_liveness_score_decline_threshold: - Ensure this value is less than or equal to 100. '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/age-estimation/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'age_estimation_decline_threshold=18' \ -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.age_estimation.estimate( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, age_estimation_decline_threshold=18, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "age-gate"}, ) 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.ageEstimation.estimate({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\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.AgeEstimationEstimateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .ageEstimationDeclineThreshold(18L) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "age-gate")) .build()); System.out.println(result); - lang: php label: PHP source: |- ageEstimation->estimate([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'age_estimation_decline_threshold' => 18, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'age-gate'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.age_estimation.estimate( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" } ) 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.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, AgeEstimationDeclineThreshold = 18, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "age-gate" }, }); 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.