Usare GenderAPI.io V2 con JavaScript e Node.js

Mantenere l'integrazione su un server Node.js

Questa guida chiama l'endpoint di GenderAPI.io V2 https://api.genderapi.io/api/v2/gender con la chiave API nell'intestazione Bearer. Usa Node.js 22 o versioni successive e scarica genderapi-v2.mjs nel tuo progetto. Il modulo ES usa fetch e AbortSignal.timeout integrati; non richiede alcun pacchetto npm. Grazie all'estensione .mjs puoi importarlo da un altro modulo ES senza modificare package.json.

Imposta GENDERAPI_API_KEY nell'ambiente del server. Non inserirla nel codice JavaScript di React, Vue o in altro codice eseguito nel browser. Lascia che sia il tuo server ad autenticare gli utenti dell'applicazione e a chiamare GenderAPI.io. YOUR_API_KEY nell'esempio seguente non è una chiave valida; importare il modulo o eseguirlo senza un'opzione di esecuzione esplicita non invia alcuna richiesta.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Scarica genderapi-v2.mjs →
• Verificare la chiave con l'endpoint gratuito di utilizzo →

Inviare una richiesta POST con JSON e una policy IA esplicita

Salva il codice come single.mjs accanto al modulo scaricato ed esegui node single.mjs. Invia i campi V2 type e value insieme a options.ai_mode: off. La previsione si legge in response.data, mentre le informazioni sulla richiesta e sull'addebito si trovano in response.meta.

Una ricerca completata costa 1 credito, anche quando gender è null; il nome di esempio non garantisce un risultato determinato.

Il modulo di supporto richiede una modalità IA esplicita e una chiave esadecimale di 24 caratteri, poi verifica che meta.access.mode abbia il valore api_key. Una risposta riuscita della prova genera un errore di modalità di accesso inattesa invece di proseguire tacitamente. Il server può aver già consumato un credito di prova prima che il modulo rilevi la differenza.

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

• Tutti i campi delle richieste singole →

Salvare il risultato insieme alle evidenze

Un'associazione dedotta non è il genere dichiarato da una persona. Salva separatamente l'input originale, le evidenze restituite e ciò che la persona ha dichiarato. Un risultato sconosciuto è un risultato valido e non dovrebbe diventare una categoria indovinata nella tua applicazione.

• Campi della risposta e risultati sconosciuti →
• Accuratezza e confidenza spiegate →
• Fonti dei dati e profilo datato del database →

Elaborare un batch misto e conservare l'id di ogni riga

GenderAPI.io V2 elabora batch misti tramite POST https://api.genderapi.io/api/v2/gender/batch: fino a 50 elementi con una chiave dell'account o 10 con la prova IP. Questi esempi richiedono una chiave dell'account. Assegna a ogni elemento un id stabile e univoco e una modalità IA esplicita. Un batch può combinare nomi, indirizzi email e nomi utente, e ogni elemento può avere un contesto country facoltativo.

Leggi ogni elemento in data e il riepilogo in meta.summary. Una risposta HTTP 200 può contenere errori di singoli elementi; un batch in cui tutti gli elementi non sono riusciti può restituire una risposta Problem di primo livello con i risultati. I risultati sconosciuti riusciti vengono contati in succeeded. Con index e id colleghi ogni risultato alla riga di origine corretta.

Per i lavori più grandi suddividi l'input in gruppi di al massimo 50 elementi e inviali inizialmente uno alla volta. Salva ogni risposta e il relativo utilizzo prima di passare al gruppo successivo. Fermati in caso di errore di trasporto, di errore di accesso all'account o di addebito non confermato e chiarisci la situazione del gruppo corrente. Introduci invii paralleli solo dopo aver verificato i limiti del tuo account; la dimensione massima del batch non garantisce una determinata capacità di elaborazione.

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, risultati e addebito dei batch →

Decidere quando usare l'IA

forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente. Quando è attivo, ometti ai_mode o usa fallback; off e always non possono essere combinati con questa opzione e restituiscono 422. Un saldo iniziale positivo basta per avviare una richiesta, anche se l'addebito finale rende il saldo negativo.

La modalità nickname può restituire un genere insieme a name: null. Può anche dare un risultato sconosciuto. Né il normale fallback IA né l'interpretazione dei nickname garantiscono una risposta corretta o un valore diverso da null.

Il modulo di supporto per JavaScript richiede sempre options.ai_mode. Per l'interpretazione dei nickname invia forceToGenderize: true insieme a options: { ai_mode: 'fallback' }.

• Opzioni IA e interpretazione dei nickname →
• Crediti e utilizzo →

Decidere che cosa fare dopo un errore

Gli esempi inviano ogni operazione una sola volta. Non la ripetono mai automaticamente: un nuovo invio è una nuova operazione soggetta ad addebito. Un timeout o un errore di connessione significa che il client non ha ricevuto una risposta completa; non dimostra che il server abbia interrotto l'elaborazione né che non siano stati addebitati crediti.

Salva il request_id restituito e lo stato dell'addebito insieme al record del tuo lavoro. L'oggetto di errore conserva la risposta per un'analisi controllata, ma può contenere l'input originale: non scrivere nei log ordinari né l'intero oggetto né la risposta né la chiave API.

• Problem Details e decisioni sui nuovi tentativi →
• Crediti e conferma dell'addebito →

Conoscere il timeout di fetch e i controlli sulla risposta

Il timeout predefinito è di 10.000 millisecondi tramite AbortSignal.timeout, inclusa la lettura del corpo della risposta. Un'interruzione lato client non dimostra che l'elaborazione o l'addebito sul server siano stati interrotti. Il modulo disattiva i reindirizzamenti, distingue gli errori HTTP dalle risposte illeggibili e non ripete mai automaticamente le richieste.

I test con trasporto simulato coprono risposte riuscite, risultati sconosciuti, batch parzialmente riusciti, fallback delle credenziali ed errori. Non richiedono previsioni reali né operazioni con crediti; non misurano la disponibilità o l'accuratezza in produzione. Ogni comando demo esplicito riportato di seguito invia una propria richiesta soggetta ad addebito.

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

• Documentazione Node.js su fetch →
• Documentazione Node.js su AbortSignal.timeout →

Domande frequenti