JavaScriptとNode.jsでGenderAPI.io V2を使う

連携はNode.jsのサーバー上に置く

このガイドでは、BearerのAPIキーを使ってGenderAPI.io V2のエンドポイントhttps://api.genderapi.io/api/v2/genderを呼び出します。Node.js 22以降を使い、genderapi-v2.mjsをプロジェクトにダウンロードしてください。このESモジュールは組み込みのfetchとAbortSignal.timeoutを使うため、npmのパッケージは必要ありません。拡張子が.mjsなので、package.jsonを変更せずに別のESモジュールからインポートできます。

サーバーの環境にGENDERAPI_API_KEYを設定してください。キーをReact、Vue、その他のブラウザーで動くJavaScriptに含めないでください。アプリケーションのユーザーの認証は自分のサーバーで行い、GenderAPI.ioの呼び出しもサーバーから行ってください。以下の例のYOUR_API_KEYは有効なキーではありません。モジュールをインポートしたり、明示的な実行オプションを付けずに実行したりしても、リクエストは送信されません。

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi-v2.mjsをダウンロード →
• 無料の使用状況エンドポイントでキーを確認する →

明示的なAIの方針を付けてJSONのPOSTを1回送信する

このコードをダウンロードしたモジュールと同じ場所にsingle.mjsとして保存し、node single.mjsを実行します。V2のフィールドtypeとvalueを、options.ai_mode: offとともに送信します。推定結果はresponse.dataで、リクエストと課金の詳細はresponse.metaで確認してください。

完了した検索は、genderがnullでも1クレジットを消費します。サンプルの名前で特定の結果が得られるとは限りません。

ヘルパーは、明示的なAIモードと24文字の16進数のキーを求め、meta.access.modeがapi_keyであることを確認します。IPトライアルの成功レスポンスは、黙って処理を続けるのではなく、想定外のアクセスモードのエラーになります。ヘルパーがこの不一致を検出する前に、サーバーがIPトライアルのクレジットをすでに1回分消費していることがあります。

import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}

• 単一リクエストのすべてのフィールド →

結果とその根拠をあわせて保存する

推定された関連付けは、本人が申告した性別ではありません。元の入力、返された根拠、本人から提供された情報は分けて保存してください。不明な結果は有効な結果であり、アプリケーション内で推測によるカテゴリーに置き換えるべきではありません。

• レスポンスフィールドと不明な結果 →
• 精度と信頼度の説明 →
• データソースと日付付きのデータベース概要 →

混在したバッチを処理し、行のidを保持する

GenderAPI.io V2では、混在したバッチをPOST https://api.genderapi.io/api/v2/gender/batchで処理します。アカウントのキーでは最大50項目、IPトライアルでは最大10項目です。これらの例にはアカウントのキーが必要です。すべての項目に、安定した一意のidと明示的なAIモードを指定してください。1つのバッチに名前、メールアドレス、ユーザー名を混在させることができ、各項目に任意で国のコンテキストを指定できます。

dataに含まれるすべての項目と、meta.summaryの集計を確認してください。HTTP 200でも項目のエラーが含まれることがあります。すべての項目が失敗したバッチは、結果を含むトップレベルのProblemレスポンスになることがあります。成功した不明な結果はsucceededとして数えられます。元のindexとidを使うと、各結果を正しい元の行に対応付けられます。

大きなジョブでは、入力を最大50項目ずつのグループに分け、最初は順番に送信してください。次に進む前に、各レスポンスとその使用状況を保存します。通信、アカウント、未確定の課金に関する失敗が起きたら処理を止め、現在のグループの状況を確認してください。並列処理は、アカウントの上限を確認してから追加してください。バッチの最大項目数は、処理能力を保証するものではありません。

import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}

• バッチの入力、結果、課金 →

AIを使うタイミングを選ぶ

forceToGenderizeは、名前、メールアドレス、ユーザー名のいずれでも任意で使用できます。有効にする場合は、ai_modeを省略するかfallbackを使用してください。offとalwaysは併用できず、422が返ります。最終的な課金で残高がマイナスになる場合でも、開始時の残高がプラスであればリクエストを開始できます。

ニックネームモードでは、name: nullのまま性別が返ることがあります。不明な結果になることもあります。通常のフォールバックもニックネームの推定も、正しい回答やnullでない回答を保証するものではありません。

このJavaScriptのヘルパーでは、options.ai_modeが常に必要です。ニックネームの推定には、forceToGenderize: trueとoptions: { ai_mode: 'fallback' }をあわせて送信してください。

• AIオプションとニックネームの推定 →
• クレジットと使用状況 →

失敗した後の対応を決める

例では、各操作を1回だけ送信します。自動的に再試行することはありません。再送は新しい操作であり、課金の対象になります。タイムアウトや接続の失敗は、クライアントが完全なレスポンスを受け取れなかったことを意味します。サーバーが処理を止めたことや、クレジットが消費されなかったことを証明するものではありません。

返されたリクエストIDと課金の状態を、ジョブの記録とあわせて保存してください。エラーオブジェクトは、管理された形で確認できるようにレスポンスを保持しますが、元の入力が含まれていることがあります。オブジェクト全体、レスポンス、APIキーを通常のログに書き込まないでください。

• Problem Detailsと再試行の判断 →
• クレジットと課金の確認 →

fetchのタイムアウトとレスポンスの確認を理解する

デフォルトのタイムアウトは、AbortSignal.timeoutを使った10,000ミリ秒で、レスポンスの本文の読み取りも含まれます。クライアントが中断しても、サーバーでの処理や課金が止まったことにはなりません。このモジュールはリダイレクトを無効にし、HTTPの失敗と読み取れないレスポンスを区別し、自動的に再試行することはありません。

通信のフィクスチャーを使ったテストでは、成功したレスポンス、不明な結果、部分的に失敗したバッチ、認証情報のフォールバック、エラーを確認します。これらのテストには実際の推定やクレジットの操作は必要なく、本番の可用性や精度のベンチマークでもありません。下にある明示的なデモのコマンドは、それぞれ独自のリクエストを送信し、課金されます。

node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch

• Node.jsのリファレンス：fetch →
• Node.jsのリファレンス：AbortSignal.timeout →

よくある質問