Brug GenderAPI.io V2 med JavaScript og Node.js

Hold integrationen på en Node.js-server

Denne guide kalder endpointet i GenderAPI.io V2 https://api.genderapi.io/api/v2/gender med API-nøglen i Bearer-headeren. Brug Node.js 22 eller nyere, og download genderapi-v2.mjs til dit projekt. ES-modulet bruger den indbyggede fetch og AbortSignal.timeout; der kræves ingen npm-pakke. Takket være filtypen .mjs kan du importere modulet fra et andet ES-modul uden at ændre package.json.

Angiv GENDERAPI_API_KEY i serverens miljø. Læg ikke nøglen i JavaScript-kode til React, Vue eller anden kode, der køres i browseren. Lad din server autentificere applikationens brugere og kalde GenderAPI.io. YOUR_API_KEY i det følgende eksempel er ikke en gyldig nøgle, og at importere modulet eller køre det uden en eksplicit kørselsindstilling sender ingen forespørgsel.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Download genderapi-v2.mjs →
• Kontrollér nøglen med det gratis endpoint for forbrug →

Send en POST-forespørgsel med JSON og en eksplicit AI-politik

Gem koden som single.mjs ved siden af det downloadede modul, og kør node single.mjs. Forespørgslen sender V2-felterne type og value sammen med options.ai_mode: off. Forudsigelsen står i response.data, mens oplysningerne om forespørgslen og opkrævningen står i response.meta.

Et afsluttet opslag koster 1 kredit, også når gender er null, og eksempelnavnet garanterer ikke et bestemt resultat.

Hjælpemodulet kræver en eksplicit AI-tilstand og en hexadecimal nøgle på 24 tegn og kontrollerer derefter, om meta.access.mode har værdien api_key. Et gennemført svar fra prøveadgangen giver en fejl om en uventet adgangstilstand i stedet for i stilhed at fortsætte. Serveren kan allerede have brugt en kredit fra prøveadgangen, før modulet opdager forskellen.

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 felter i enkeltforespørgsler →

Gem resultatet sammen med evidensen

En udledt sammenhæng er ikke det køn, en person selv har oplyst. Gem det oprindelige input, den returnerede evidens og det, personen selv har oplyst, hver for sig. Et ukendt resultat er et gyldigt resultat og bør ikke blive til en gættet kategori i din applikation.

• Svarfelter og ukendte resultater →
• Nøjagtighed og konfidens forklaret →
• Datakilder og databasens daterede profil →

Behandl en blandet batch, og bevar id'et for hver række

GenderAPI.io V2 behandler blandede batches via POST https://api.genderapi.io/api/v2/gender/batch: op til 50 elementer med en kontonøgle eller 10 med IP-prøveadgangen. Disse eksempler kræver en kontonøgle. Giv hvert element et stabilt, unikt id og en eksplicit AI-tilstand. En batch kan kombinere navne, e-mailadresser og brugernavne, og hvert element kan have en valgfri country-kontekst.

Læs hvert element i data og oversigten i meta.summary. Et HTTP 200-svar kan indeholde fejl i enkelte elementer, og en batch, hvor alle elementer er mislykkedes, kan returnere et Problem-svar på øverste niveau med resultaterne. Gennemførte ukendte resultater tælles med i succeeded. Med index og id knytter du hvert resultat til den rigtige oprindelige række.

Del større opgaver op i grupper på højst 50 elementer, og send dem i begyndelsen én ad gangen. Gem hvert svar og det tilhørende forbrug, før du går videre til næste gruppe. Stop ved en transportfejl, en fejl i adgangen til kontoen eller en ubekræftet opkrævning, og find først ud af, hvad der skete med den aktuelle gruppe. Send først parallelt, når du har kontrolleret din kontos grænser. Den maksimale batchstørrelse garanterer ikke en bestemt behandlingskapacitet.

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

• Input, resultater og opkrævning for batches →

Beslut, hvornår AI skal bruges

forceToGenderize er valgfrit for navne, e-mailadresser og brugernavne. Når det er slået til, skal du udelade ai_mode eller bruge fallback. off og always kan ikke kombineres med denne indstilling og returnerer 422. En positiv startsaldo er nok til at starte en forespørgsel, også selvom den endelige opkrævning gør saldoen negativ.

Kaldenavnstilstanden kan returnere et køn sammen med name: null. Den kan også give et ukendt resultat. Hverken den almindelige automatiske AI-fallback eller fortolkningen af kaldenavne garanterer et korrekt svar eller en værdi, der ikke er null.

Hjælpemodulet til JavaScript kræver altid options.ai_mode. Send forceToGenderize: true sammen med options: { ai_mode: 'fallback' } til fortolkning af kaldenavne.

• AI-indstillinger og fortolkning af kaldenavne →
• Kreditter og forbrug →

Beslut, hvad du gør efter en fejl

Eksemplerne sender hver handling én gang. De gentager den aldrig automatisk: At sende igen er en ny handling, som kan blive opkrævet. En timeout eller en forbindelsesfejl betyder, at klienten ikke har modtaget et fuldstændigt svar. Det beviser ikke, at serveren har stoppet behandlingen, eller at der ikke er opkrævet kreditter.

Gem det returnerede request_id og opkrævningens status sammen med posten for din opgave. Fejlobjektet bevarer svaret til kontrolleret analyse, men kan indeholde det oprindelige input: Skriv ikke hele objektet, svaret og API-nøglen i almindelige logfiler.

• Problem Details og beslutninger om nye forsøg →
• Kreditter og bekræftelse af opkrævningen →

Kend timeouten for fetch og kontrollerne af svaret

Standardtimeouten er 10.000 millisekunder via AbortSignal.timeout, inklusive læsning af svarets body. En afbrydelse på klientsiden beviser ikke, at behandlingen eller opkrævningen på serveren er stoppet. Modulet slår omdirigeringer fra, skelner mellem HTTP-fejl og ulæselige svar og gentager aldrig forespørgsler automatisk.

Testene med simuleret transport dækker gennemførte svar, ukendte resultater, delvist gennemførte batches, fallback ved loginoplysninger og fejl. De henter ingen rigtige forudsigelser og udfører ingen handlinger med kreditter, og de måler ikke tilgængelighed eller nøjagtighed i produktion. Hver eksplicit demokommando nedenfor sender sin egen forespørgsel, som bliver opkrævet.

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

• Node.js-dokumentation om fetch →
• Node.js-dokumentation om AbortSignal.timeout →

Ofte stillede spørgsmål