Použití GenderAPI.io V2 s JavaScriptem a Node.js

Ponechte integraci na svém serveru Node.js

Tento průvodce volá endpoint GenderAPI.io V2 https://api.genderapi.io/api/v2/gender s API klíčem jako tokenem Bearer. Použijte Node.js 22 nebo novější a stáhněte si genderapi-v2.mjs do svého projektu. Tento modul ES používá vestavěné fetch a AbortSignal.timeout; žádný balíček npm není potřeba. Díky příponě .mjs můžete modul importovat z jiného modulu ES bez úpravy package.json.

Nastavte GENDERAPI_API_KEY v prostředí serveru. Klíč nepřidávejte do balíčku pro React, Vue ani do JavaScriptu, který běží v prohlížeči. Uživatele aplikace nechte ověřovat vlastní server a GenderAPI.io volejte z něj. YOUR_API_KEY v příkladu níže není platný klíč. Import modulu ani jeho spuštění bez výslovné volby pro spuštění neodešle žádný požadavek.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Stáhnout genderapi-v2.mjs →
• Ověřte klíč pomocí bezplatného endpointu pro využití →

Odešlete jeden JSON POST s výslovnými pravidly AI

Uložte kód jako single.mjs vedle staženého modulu a spusťte node single.mjs. Odešle pole V2 type a value s options.ai_mode: off. Odhad čtěte v response.data a údaje o požadavku a účtování v response.meta.

Dokončené vyhledání stojí 1 kredit, i když je gender null; ukázkové jméno nezaručuje konkrétní výsledek.

Pomocný modul vyžaduje výslovný režim AI a hexadecimální klíč o 24 znacích a potom kontroluje, že meta.access.mode je api_key. Úspěšná odpověď ze zkušebního režimu vyvolá chybu nesouladu režimu přístupu, místo aby se tiše pokračovalo. Server mohl kredit ze zkušebního režimu spotřebovat dřív, než pomocný modul nesoulad zjistí.

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

• Všechna pole jednotlivých požadavků →

Uchovávejte výsledek spolu s jeho podklady

Odvozené přiřazení není pohlaví, které osoba sama uvedla. Původní vstup, vrácené podklady a údaje, které poskytla sama osoba, uchovávejte odděleně. Neznámý výsledek je platný výsledek a ve vaší aplikaci by se z něj neměla stát odhadnutá kategorie.

• Pole odpovědi a neznámé výsledky →
• Vysvětlení přesnosti a spolehlivosti →
• Zdroje dat a datovaný profil datové sady →

Zpracujte smíšenou dávku a zachovejte id každého řádku

GenderAPI.io V2 používá pro smíšené dávky POST https://api.genderapi.io/api/v2/gender/batch: nejvýše 50 položek s klíčem účtu nebo 10 ve zkušebním režimu podle IP. Tyto příklady vyžadují klíč účtu. Každé položce přidělte stabilní jedinečné id a výslovný režim AI. Dávka může kombinovat jména, e-mailové adresy a uživatelská jména a každá položka může mít volitelný kontext země.

Čtěte každou položku v data a souhrn v meta.summary. Odpověď HTTP 200 může obsahovat chyby jednotlivých položek; dávka, ve které selhaly všechny položky, může vrátit odpověď Problem na nejvyšší úrovni, která výsledky obsahuje. Úspěšné neznámé výsledky se počítají jako succeeded. Díky původním index a id přiřadíte každý výsledek ke správnému zdrojovému řádku.

U větších úloh rozdělte vstup do skupin po nejvýše 50 položkách a zpočátku je odesílejte postupně. Před pokračováním uložte každou odpověď a využití. Při chybě přenosu, chybě účtu nebo nepotvrzeném účtování se zastavte a aktuální skupinu odsouhlaste. Souběžné požadavky přidávejte až po kontrole limitů svého účtu; největší povolená dávka není zárukou kapacity.

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

• Vstup, výsledky a účtování dávek →

Rozhodněte, kdy použít AI

forceToGenderize je volitelné pro jména, e-mailové adresy i uživatelská jména. Pokud je zapnuté, ai_mode vynechte nebo použijte fallback; off a always jsou s ním v konfliktu a vrátí 422. K zahájení požadavku stačí kladný počáteční zůstatek, i když konečné vyúčtování dostane zůstatek do záporu.

Režim přezdívek může vrátit pohlaví spolu s name: null. Může také vrátit neznámý výsledek. Běžná záložní AI ani analýza přezdívek nezaručuje správnou odpověď ani hodnotu jinou než null.

Tento pomocný modul pro JavaScript vždy vyžaduje options.ai_mode. Pro analýzu přezdívek odešlete forceToGenderize: true spolu s options: { ai_mode: 'fallback' }.

• Možnosti AI a analýza přezdívek →
• Kredity a využití →

Rozhodněte, co udělat po selhání

Příklady odesílají každou operaci jednou. Automaticky ji neopakují: nové odeslání je nová operace, která se účtuje. Vypršení časového limitu nebo chyba připojení znamená, že klient nedostal úplnou odpověď; nedokazuje to, že se server zastavil ani že nebyly účtovány žádné kredity.

ID požadavku a vrácený stav účtování uchovávejte spolu se záznamem úlohy. Objekt chyby zachovává odpověď pro kontrolované prozkoumání, může však obsahovat původní vstup; celý objekt, odpověď ani API klíč nezapisujte do běžných protokolů.

• Problem Details a rozhodování o opakování →
• Kredity a potvrzení účtování →

Časový limit fetch a kontroly odpovědi

Výchozí časový limit je 10 000 milisekund pomocí AbortSignal.timeout, včetně čtení těla odpovědi. Přerušení na straně klienta nedokazuje, že se zpracování nebo účtování na serveru zastavilo. Modul vypíná přesměrování, odlišuje chyby HTTP od nečitelných odpovědí a nikdy automaticky neopakuje požadavky.

Testy se syntetickými odpověďmi přenosu pokrývají úspěšné odpovědi, neznámé výsledky, částečně úspěšné dávky, náhradní postupy pro přihlašovací údaje a chyby. Testy nepotřebují skutečné odhady ani operace s kredity; nejsou měřením dostupnosti ani přesnosti v provozu. Každý volitelný příkaz ukázky níže odešle vlastní požadavek, který se účtuje.

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

• Dokumentace Node.js: fetch →
• Dokumentace Node.js: AbortSignal.timeout →

Časté dotazy