Bruk GenderAPI.io V2 med JavaScript og Node.js

Hold integrasjonen på Node.js-serveren din

Denne veiledningen kaller endepunktet https://api.genderapi.io/api/v2/gender i GenderAPI.io V2 med en API-nøkkel som Bearer-token. Bruk Node.js 22 eller nyere, og last ned genderapi-v2.mjs til prosjektet ditt. Denne ES-modulen bruker den innebygde fetch og AbortSignal.timeout; ingen npm-pakke er nødvendig. Med filtypen .mjs kan du importere modulen fra en annen ES-modul uten å endre package.json.

Angi GENDERAPI_API_KEY i miljøet på serveren. Ikke pakk nøkkelen inn i React, Vue eller JavaScript som kjører i nettleseren. La din egen server autentisere brukerne av applikasjonen og kalle GenderAPI.io. YOUR_API_KEY i eksemplet nedenfor er ikke en gyldig nøkkel. Å importere modulen eller kjøre den uten et eksplisitt kjørealternativ sender ingen forespørsel.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Last ned genderapi-v2.mjs →
• Kontroller nøkkelen med det gratis endepunktet for forbruk →

Send én JSON POST med eksplisitte KI-regler

Lagre koden som single.mjs ved siden av den nedlastede modulen, og kjør node single.mjs. Den sender V2-feltene type og value med options.ai_mode: off. Les estimatet i response.data og opplysningene om forespørselen og belastningen i response.meta.

Et fullført oppslag koster 1 kreditt også når gender er null; eksempelnavnet garanterer ikke et bestemt resultat.

Hjelpemodulen krever en eksplisitt KI-modus og en heksadesimal nøkkel på 24 tegn og kontrollerer deretter at meta.access.mode er api_key. Et vellykket svar fra prøveperioden gir en feil om at tilgangsmodusen ikke stemmer, i stedet for å fortsette i det stille. Serveren kan allerede ha brukt en kreditt fra prøveperioden før hjelpemodulen oppdager avviket.

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 felt i enkeltforespørsler →

Lagre resultatet sammen med grunnlaget

En utledet tilknytning er ikke det kjønnet en person selv har oppgitt. Lagre de opprinnelige inndataene, grunnlaget som ble returnert, og det personen selv har oppgitt, hver for seg. Et ukjent resultat er et gyldig resultat og bør ikke bli en gjettet kategori i applikasjonen din.

• Svarfelt og ukjente resultater →
• Nøyaktighet og konfidens forklart →
• Datakilder og den daterte profilen til datasettet →

Behandle en blandet samleforespørsel og behold id-en for hver rad

GenderAPI.io V2 bruker POST https://api.genderapi.io/api/v2/gender/batch for blandede samleforespørsler: høyst 50 elementer med en kontonøkkel eller 10 i IP-prøveperioden. Disse eksemplene krever en kontonøkkel. Gi hvert element en stabil, unik id og en eksplisitt KI-modus. En samleforespørsel kan kombinere navn, e-postadresser og brukernavn, og hvert element kan ha en valgfri landkontekst.

Les hvert element i data og sammendraget i meta.summary. Et HTTP 200-svar kan inneholde feil for enkeltelementer; en samleforespørsel der alle elementene mislyktes, kan gi et Problem-svar på øverste nivå som inneholder resultatene. Vellykkede ukjente resultater telles som succeeded. Med den opprinnelige index og id kan du knytte hvert utfall til riktig kilderad.

Ved større jobber deler du inndataene i grupper på høyst 50 og sender dem først etter hverandre. Lagre hvert svar og forbruket før du går videre. Stopp ved feil i overføringen, feil med kontoen eller en belastning som ikke er bekreftet, og stem av den gjeldende gruppen. Legg bare til parallelle forespørsler etter at du har kontrollert grensene for kontoen din; den største tillatte samleforespørselen er ingen garanti for kapasitet.

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

• Inndata, resultater og belastning for samleforespørsler →

Bestem når KI skal brukes

forceToGenderize er valgfritt for navn, e-postadresser og brukernavn. Når det er aktivert, utelater du ai_mode eller bruker fallback; off og always kan ikke kombineres med dette alternativet og gir 422. En positiv startsaldo er nok til å starte en forespørsel, selv om den endelige belastningen gjør saldoen negativ.

Kallenavnmodus kan returnere et kjønn sammen med name: null. Den kan også gi et ukjent resultat. Verken vanlig KI-reserve eller tolkning av kallenavn garanterer et riktig svar eller en verdi som ikke er null.

Denne hjelpemodulen for JavaScript krever alltid options.ai_mode. For tolkning av kallenavn sender du forceToGenderize: true sammen med options: { ai_mode: 'fallback' }.

• KI-alternativer og tolkning av kallenavn →
• Kreditter og forbruk →

Bestem hva du gjør etter en feil

Eksemplene sender hver operasjon én gang. De prøver ikke på nytt automatisk: En ny innsending er en ny operasjon som belastes. Et tidsavbrudd eller en tilkoblingsfeil betyr at klienten ikke fikk et fullstendig svar; det beviser ikke at serveren stoppet, eller at ingen kreditter ble belastet.

Lagre forespørsels-ID-en og belastningsstatusen som returneres, sammen med posten for jobben. Feilobjektet beholder svaret slik at det kan undersøkes kontrollert, men det kan inneholde de opprinnelige inndataene; ikke skriv hele objektet, svaret eller API-nøkkelen til vanlige logger.

• Problem Details og beslutninger om nye forsøk →
• Kreditter og bekreftelse av belastningen →

Forstå tidsavbruddet for fetch og kontrollene av svaret

Standard tidsavbrudd er 10 000 millisekunder med AbortSignal.timeout, inkludert lesing av innholdet i svaret. At klienten avbryter, beviser ikke at behandlingen eller belastningen på serveren stoppet. Modulen slår av omdirigeringer, skiller HTTP-feil fra svar som ikke kan leses, og prøver aldri på nytt automatisk.

Tester med syntetiske overføringssvar dekker vellykkede svar, ukjente resultater, delvis vellykkede samleforespørsler, reserveløsninger for påloggingsopplysninger og feil. Testene trenger ingen ekte prediksjoner eller operasjoner med kreditter; de er ikke en måling av tilgjengelighet eller nøyaktighet i drift. Hver valgfri demokommando nedenfor sender sin egen forespørsel, som belastes.

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

• Node.js-dokumentasjon: fetch →
• Node.js-dokumentasjon: AbortSignal.timeout →

Ofte stilte spørsmål