GenderAPI.io V2 gebruiken met JavaScript en Node.js

De integratie op een Node.js-server houden

Deze handleiding roept het endpoint van GenderAPI.io V2 https://api.genderapi.io/api/v2/gender aan met de API-sleutel in de Bearer-header. Gebruik Node.js 22 of hoger en download genderapi-v2.mjs naar uw project. De ES-module gebruikt de ingebouwde fetch en AbortSignal.timeout; er is geen npm-pakket nodig. Dankzij de extensie .mjs kunt u de module vanuit een andere ES-module importeren zonder package.json aan te passen.

Stel GENDERAPI_API_KEY in de omgeving van de server in. Zet de sleutel niet in JavaScript-code van React, Vue of andere code die in de browser wordt uitgevoerd. Laat uw server de gebruikers van de applicatie authenticeren en GenderAPI.io aanroepen. YOUR_API_KEY in het volgende voorbeeld is geen geldige sleutel; het importeren van de module of het uitvoeren ervan zonder expliciete uitvoeringsoptie verstuurt geen verzoek.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi-v2.mjs downloaden →
• De sleutel controleren met het gratis gebruiksendpoint →

Een POST-verzoek met JSON en een expliciet AI-beleid versturen

Sla de code op als single.mjs naast de gedownloade module en voer node single.mjs uit. Het verzoek verstuurt de V2-velden type en value samen met options.ai_mode: off. De voorspelling staat in response.data, terwijl de informatie over het verzoek en de afschrijving in response.meta staat.

Een afgeronde zoekopdracht kost 1 credit, ook als gender null is; de voorbeeldnaam garandeert geen bepaald resultaat.

De hulpmodule vereist een expliciete AI-modus en een hexadecimale sleutel van 24 tekens en controleert daarna of meta.access.mode de waarde api_key heeft. Een geslaagd antwoord van de proefperiode geeft een fout voor een onverwachte toegangsmodus in plaats van stilzwijgend door te gaan. De server kan al een credit van de proefperiode hebben verbruikt voordat de module het verschil opmerkt.

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 velden van losse verzoeken →

Het resultaat samen met het bewijs opslaan

Een afgeleide koppeling is niet het geslacht dat iemand zelf opgeeft. Sla de oorspronkelijke invoer, het teruggegeven bewijs en wat de persoon zelf heeft opgegeven apart op. Een onbekend resultaat is een geldig resultaat en mag in uw applicatie geen geraden categorie worden.

• Antwoordvelden en onbekende resultaten →
• Nauwkeurigheid en betrouwbaarheidsscore uitgelegd →
• Gegevensbronnen en gedateerd profiel van de database →

Een gemengde batch verwerken en de id van elke rij bewaren

GenderAPI.io V2 verwerkt gemengde batches via POST https://api.genderapi.io/api/v2/gender/batch: maximaal 50 items met een accountsleutel of 10 met de IP-proefperiode. Deze voorbeelden vereisen een accountsleutel. Geef elk item een stabiele, unieke id en een expliciete AI-modus. Een batch kan namen, e-mailadressen en gebruikersnamen combineren, en elk item kan een optionele country-context hebben.

Lees elk item in data en de samenvatting in meta.summary. Een HTTP 200-antwoord kan fouten in afzonderlijke items bevatten; een batch waarin alle items zijn mislukt, kan een Problem-antwoord op het hoogste niveau met de resultaten teruggeven. Geslaagde onbekende resultaten worden meegeteld in succeeded. Met index en id koppelt u elk resultaat aan de juiste oorspronkelijke rij.

Verdeel grotere taken in groepen van maximaal 50 items en verstuur die in het begin een voor een. Sla elk antwoord en het bijbehorende gebruik op voordat u naar de volgende groep gaat. Stop bij een transportfout, een fout bij de toegang tot het account of een onbevestigde afschrijving en zoek eerst uit wat er met de huidige groep is gebeurd. Verstuur pas parallel nadat u de limieten van uw account hebt gecontroleerd; de maximale batchgrootte garandeert geen bepaalde verwerkingscapaciteit.

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

• Invoer, resultaten en afschrijving van batches →

Bepalen wanneer u AI gebruikt

forceToGenderize is optioneel voor namen, e-mailadressen en gebruikersnamen. Als het is ingeschakeld, laat ai_mode dan weg of gebruik fallback; off en always kunnen niet met deze optie worden gecombineerd en geven 422 terug. Een positief beginsaldo is genoeg om een verzoek te starten, ook als de uiteindelijke afschrijving het saldo negatief maakt.

De bijnaammodus kan een geslacht teruggeven samen met name: null. Ook een onbekend resultaat is mogelijk. Noch de normale AI-fallback noch de bijnaaminterpretatie garandeert een juist antwoord of een waarde anders dan null.

De hulpmodule voor JavaScript vereist altijd options.ai_mode. Verstuur voor bijnaaminterpretatie forceToGenderize: true samen met options: { ai_mode: 'fallback' }.

• AI-opties en bijnaaminterpretatie →
• Credits en gebruik →

Bepalen wat u doet na een fout

De voorbeelden versturen elke bewerking één keer. Ze herhalen die nooit automatisch: opnieuw versturen is een nieuwe bewerking waarvoor een afschrijving kan gelden. Een time-out of verbindingsfout betekent dat de client geen volledig antwoord heeft ontvangen; het bewijst niet dat de server de verwerking heeft gestopt of dat er geen credits zijn afgeschreven.

Sla de teruggegeven request_id en de status van de afschrijving op bij het record van uw taak. Het foutobject bewaart het antwoord voor gecontroleerde analyse, maar kan de oorspronkelijke invoer bevatten: schrijf het volledige object, het antwoord en de API-sleutel niet naar gewone logs.

• Problem Details en beslissingen over nieuwe pogingen →
• Credits en bevestiging van de afschrijving →

De time-out van fetch en de controles op het antwoord kennen

De standaardtime-out is 10.000 milliseconden via AbortSignal.timeout, inclusief het lezen van de body van het antwoord. Een afbreking aan de clientkant bewijst niet dat de verwerking of de afschrijving op de server is gestopt. De module schakelt omleidingen uit, maakt onderscheid tussen HTTP-fouten en onleesbare antwoorden en herhaalt verzoeken nooit automatisch.

De tests met gesimuleerd transport dekken geslaagde antwoorden, onbekende resultaten, gedeeltelijk geslaagde batches, terugval bij inloggegevens en fouten. Ze vragen geen echte voorspellingen op en voeren geen bewerkingen met credits uit; ze meten de beschikbaarheid of nauwkeurigheid in productie niet. Elk expliciet democommando hieronder verstuurt een eigen verzoek waarvoor een afschrijving geldt.

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

• Node.js-documentatie over fetch →
• Node.js-documentatie over AbortSignal.timeout →

Veelgestelde vragen