GenderAPI.io V2 mit JavaScript und Node.js verwenden

Die Integration auf einem Node.js-Server halten

Diese Anleitung ruft den Endpunkt von GenderAPI.io V2 https://api.genderapi.io/api/v2/gender mit dem API-Schlüssel im Bearer-Header auf. Verwenden Sie Node.js 22 oder neuer und laden Sie genderapi-v2.mjs in Ihr Projekt herunter. Dieses ES-Modul nutzt die integrierten fetch und AbortSignal.timeout; es benötigt kein npm-Paket. Dank der Endung .mjs können Sie es aus einem anderen ES-Modul importieren, ohne package.json zu ändern.

Setzen Sie GENDERAPI_API_KEY in der Serverumgebung. Legen Sie ihn nicht in JavaScript-Code für React, Vue oder anderen im Browser ausgeführten Code ab. Lassen Sie Ihren eigenen Server die Benutzer der Anwendung authentifizieren und GenderAPI.io aufrufen. YOUR_API_KEY im folgenden Beispiel ist kein gültiger Schlüssel; das Importieren des Moduls oder sein Start ohne ausdrückliche Ausführungsoption sendet keine Anfrage.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi-v2.mjs herunterladen →
• Schlüssel mit dem kostenlosen Nutzungsendpunkt prüfen →

Eine POST-Anfrage mit JSON und ausdrücklicher KI-Richtlinie senden

Speichern Sie diesen Code als single.mjs neben dem heruntergeladenen Modul und führen Sie dann node single.mjs aus. Er sendet die V2-Felder type und value zusammen mit options.ai_mode: off. Die Vorhersage lesen Sie aus response.data, die Angaben zur Anfrage und zur Abrechnung aus response.meta.

Eine abgeschlossene Abfrage kostet 1 Credit, auch wenn gender null ist; der Beispielname garantiert kein bestimmtes Ergebnis.

Das Hilfsmodul verlangt einen ausdrücklichen KI-Modus und einen hexadezimalen Schlüssel mit 24 Zeichen und prüft anschließend, ob meta.access.mode den Wert api_key hat. Eine erfolgreiche Antwort aus dem Testzugang löst einen Fehler wegen abweichendem Zugangsmodus aus, statt stillschweigend fortzufahren. Der Server kann bereits einen Test-Credit verbraucht haben, bevor das Modul diese Abweichung erkennt.

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;
}

• Alle Felder von Einzelanfragen →

Ergebnis und Belege gemeinsam aufbewahren

Eine abgeleitete Zuordnung ist nicht das Geschlecht, das eine Person selbst angibt. Bewahren Sie die ursprüngliche Eingabe, die zurückgegebenen Belege und alle Angaben der Person selbst getrennt auf. Ein unbekanntes Ergebnis ist ein gültiges Ergebnis; es sollte in Ihrer Anwendung nicht zu einer geratenen Kategorie werden.

• Antwortfelder und unbekannte Ergebnisse →
• Genauigkeit und Konfidenz erklärt →
• Datenquellen und das datierte Datenbankprofil →

Einen gemischten Batch verarbeiten und die ID jeder Zeile beibehalten

GenderAPI.io V2 verarbeitet gemischte Batches über POST https://api.genderapi.io/api/v2/gender/batch: bis zu 50 Einträge mit Kontoschlüssel oder 10 im IP-Testzugang. Diese Beispiele erfordern einen Kontoschlüssel. Geben Sie jedem Eintrag eine stabile, eindeutige id und einen ausdrücklichen KI-Modus. Ein Batch kann Namen, E-Mail-Adressen und Benutzernamen kombinieren, und jeder Eintrag kann einen optionalen Kontext country haben.

Lesen Sie jeden Eintrag in data sowie die Zusammenfassung meta.summary. Eine Antwort mit HTTP 200 kann Fehler einzelner Einträge enthalten; ein Batch, in dem alle Einträge fehlgeschlagen sind, kann eine Problem-Antwort der obersten Ebene mit den Ergebnissen liefern. Erfolgreiche unbekannte Ergebnisse werden in succeeded gezählt. Mit index und id ordnen Sie jedes Ergebnis der richtigen Quellzeile zu.

Teilen Sie die Eingaben bei großen Aufträgen in Gruppen von höchstens 50 Einträgen und senden Sie diese anfangs nacheinander. Speichern Sie jede Antwort und ihre Nutzung, bevor Sie zur nächsten Gruppe übergehen. Halten Sie bei einem Transportfehler, einem Fehler beim Kontozugang oder einer unbestätigten Abrechnung an und klären Sie den Stand der aktuellen Gruppe. Führen Sie paralleles Senden erst ein, nachdem Sie die Grenzen Ihres Kontos geprüft haben; die maximale Batch-Größe garantiert keinen Durchsatz.

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;
}

• Batch-Eingaben, Ergebnisse und Abrechnung →

Festlegen, wann KI eingesetzt wird

forceToGenderize ist für Namen, E-Mail-Adressen und Benutzernamen optional. Ist es aktiviert, lassen Sie ai_mode weg oder verwenden Sie fallback; off und always sind damit unvereinbar und liefern 422. Ein positives Anfangsguthaben genügt, um eine Anfrage zu starten, auch wenn die endgültige Abbuchung das Guthaben unter null senkt.

Der Spitznamenmodus kann ein Geschlecht zusammen mit name: null zurückgeben. Er kann auch ein unbekanntes Ergebnis liefern. Weder der gewöhnliche KI-Fallback noch die Spitznamen-Auswertung garantieren eine richtige Antwort oder einen Wert ungleich null.

Das JavaScript-Hilfsmodul verlangt immer options.ai_mode. Für die Spitznamen-Auswertung senden Sie forceToGenderize: true zusammen mit options: { ai_mode: 'fallback' }.

• KI-Optionen und Spitznamen-Auswertung →
• Credits und Nutzung →

Entscheiden, was nach einem Fehler geschieht

Die Beispiele senden jeden Vorgang nur einmal. Sie wiederholen ihn nie automatisch: Ein erneutes Senden ist ein neuer, kostenpflichtiger Vorgang. Eine Zeitüberschreitung oder ein Verbindungsfehler bedeutet, dass der Client keine vollständige Antwort erhalten hat; das belegt weder, dass der Server die Verarbeitung abgebrochen hat, noch dass keine Credits abgebucht wurden.

Speichern Sie die zurückgegebene request_id und den Abrechnungsstatus zusammen mit dem Datensatz Ihres Auftrags. Das Fehlerobjekt bewahrt die Antwort für eine kontrollierte Analyse auf, kann aber die ursprüngliche Eingabe enthalten: Schreiben Sie weder das gesamte Objekt noch die Antwort noch den API-Schlüssel in gewöhnliche Logs.

• Problem Details und Entscheidungen zu Wiederholungen →
• Credits und Bestätigung der Abrechnung →

Zeitüberschreitung von fetch und Antwortprüfungen kennen

Die Standard-Zeitüberschreitung beträgt 10.000 Millisekunden über AbortSignal.timeout, einschließlich des Lesens des Antwortinhalts. Ein Abbruch auf Clientseite belegt nicht, dass Verarbeitung oder Abrechnung auf dem Server gestoppt wurden. Das Modul deaktiviert Weiterleitungen, unterscheidet HTTP-Fehler von unlesbaren Antworten und wiederholt Anfragen nie automatisch.

Tests mit simuliertem Transport decken erfolgreiche Antworten, unbekannte Ergebnisse, teilweise erfolgreiche Batches, ersatzweise verwendete Zugangsdaten und Fehler ab. Sie benötigen weder echte Vorhersagen noch Operationen mit Credits; sie messen weder Verfügbarkeit noch Genauigkeit im Produktivbetrieb. Jeder ausdrückliche Demo-Befehl unten sendet eine eigene, kostenpflichtige Anfrage.

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

• Node.js-Dokumentation zu fetch →
• Node.js-Dokumentation zu AbortSignal.timeout →

Häufig gestellte Fragen