API V2のJSONレスポンスと信頼度

JSONレスポンスを理解する

成功した単一のレスポンスにはdataとmetaが含まれます。次のデータセットの例は2026年10月1日にAPIキーで取得した実際のレスポンスで、アカウント残高のみを置き換えています。測定された製品の精度を示すものではなく、実際のリクエストでは異なる結果が返ることがあります。APIキーによるリクエストではaccess.mode: api_keyが返り、IPトライアル専用の上限フィールドはnullになります。IPトライアルによるリクエストでは、トライアルの上限とリセット時刻とともにip_trialが返ります。

{
  "data": {
    "input": {
      "type": "name",
      "value": "Hiroshi",
      "country": "JP"
    },
    "name": "hiroshi",
    "gender": "male",
    "country": "JP",
    "confidence": 0.9961046188091264,
    "confidence_kind": "observed_frequency",
    "sample_count": 1797,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "hiroshi",
      "method": "normalized",
      "scope": "country",
      "country": "JP"
    }
  },
  "meta": {
    "request_id": "a7b93719-5d6e-4150-8d5d-3b494120ffe2",
    "duration_ms": 12,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

• レスポンスの完全なスキーマとバッチの例

推定のレスポンスフィールド

返される入力フィールド

データセットの照合フィールド

アクセス、課金、リクエストのメタデータ

成功した不明な結果

HTTP 200は処理が完了したことを意味し、性別が返ることを保証するものではありません。JSONのnullは、male、female、空文字列、信頼度0に変換せず、そのまま保持してください。data.result_statusとdata.reasonは、HTTPエラーとは別に確認してください。

2026年10月1日に取得したこのデータセットのみの実際の例はsource: noneとreason: not_foundを返しますが、1クレジットを消費します。件数が同数のデータセット行では、sample_countを保ったままreason: ambiguousが返ることがあります。AIによる不明な結果ではsource: aiとreason: insufficient_evidenceが使われます。

{
  "data": {
    "input": {
      "type": "name",
      "value": "zzzxxyy",
      "country": null
    },
    "name": null,
    "gender": null,
    "country": null,
    "confidence": null,
    "confidence_kind": null,
    "sample_count": null,
    "source": "none",
    "result_status": "unknown",
    "reason": "not_found",
    "country_source": null,
    "match": {
      "name": null,
      "method": null,
      "scope": null,
      "country": null
    }
  },
  "meta": {
    "request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
    "duration_ms": 10,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

信頼度と照合の根拠を解釈する

信頼度0.9は0–1の尺度での値です。observed_frequencyの場合は、多数を占める件数を選ばれたデータセットの合計件数で割った値であり、エンドツーエンドで測定した製品の精度ではありません。model_reportedのスコアはAIが提供するもので、データセットの頻度に対して較正されていません。

アプリケーションのしきい値は、独自の評価データとconfidence_kindを使って決めてください。データセットのスコアとAIのスコアを、同じものを測定しているかのように直接比較して順位付けしないでください。AIの結果ではデータセット行が選ばれていないため、match.name、match.scope、match.countryはnullで、match.methodはmodel_inferenceです。

フルネームの場合、データセットの結果は文字列全体ではなく構成要素の一部から得られることがあります。data.inputは送信された値を保持し、data.nameは返された名を、data.matchは候補と検索範囲を示します。

アプリケーションで次に何をするかを決める

まずリクエストのエラーと項目ごとのエラーを処理し、その後でresult_statusを確認してください。単一の推定ではdataを読み、バッチでは成功した各項目のdataに同じ判断を適用します。maleやfemaleのラベルを無理に付けず、不明な結果はアプリケーション内にそのまま残してください。

• 運用上の障害と不明な結果を区別する
• この判断をバッチに適用する

独自の評価に基づいてしきい値を選ぶ

推定を必ず正しくするような、共通の信頼度のしきい値はありません。利用目的に即した代表的なデータで、独立してラベル付けされた例を使い、observed_frequencyとmodel_reportedを別々に評価してください。データセットの頻度とAIが自己申告したスコアは、たとえ両方が0.9でも異なるシグナルです。方針がどれくらいの頻度で回答し、回答した推定がどれくらい正しいかを測定し、それ以外のケースは不明のまま残すか、人による確認に回してください。

例えば、result_statusがidentifiedでもconfidence_kindがmodel_reportedであれば、データセットのしきい値ではなく、評価済みのAI向けの方針を適用します。forceToGenderizeを使った場合、name: nullでnullでない性別が返るのは有効な結果です。実名を抽出しなくても、エイリアスから推定できるためです。推定が回答したかどうかは、nameだけでなくgenderとresult_statusで判断してください。これはあくまで推定であり、本人確認ではありません。

• 評価指標と信頼度の限界
• データセットの概要と根拠の範囲
• ニックネームの推定とnullになりうるname

関連ガイド

• バッチレスポンスと項目ごとのエラー
• 課金ステータスと残りのクレジット
• レスポンスの互換性と再試行