Korzystanie z GenderAPI.io V2 w JavaScript i Node.js

Utrzymuj integrację na serwerze Node.js

Ten przewodnik wywołuje endpoint GenderAPI.io V2 https://api.genderapi.io/api/v2/gender z kluczem API w nagłówku Bearer. Użyj Node.js 22 lub nowszego i pobierz genderapi-v2.mjs do swojego projektu. Ten moduł ES korzysta z wbudowanych fetch i AbortSignal.timeout; nie wymaga żadnego pakietu npm. Rozszerzenie .mjs pozwala zaimportować go z innego modułu ES bez zmieniania package.json.

Ustaw GENDERAPI_API_KEY w środowisku serwera. Nie umieszczaj go w kodzie JavaScript dla React, Vue ani w innym kodzie wykonywanym w przeglądarce. Pozwól, aby Twój własny serwer uwierzytelniał użytkowników aplikacji i wywoływał GenderAPI.io. YOUR_API_KEY w poniższym przykładzie nie jest prawidłowym kluczem; import modułu lub uruchomienie go bez jawnej opcji wykonania nie wysyła żadnego zapytania.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Pobierz genderapi-v2.mjs →
• Sprawdź klucz za pomocą bezpłatnego endpointu zużycia →

Wyślij jedno zapytanie POST z JSON i jawną polityką AI

Zapisz ten kod jako single.mjs obok pobranego modułu, a następnie uruchom node single.mjs. Wysyła on pola V2 type i value razem z options.ai_mode: off. Prognozę odczytasz z response.data, a informacje o zapytaniu i rozliczeniu z response.meta.

Zakończone wyszukiwanie kosztuje 1 kredyt, nawet gdy gender ma wartość null; przykładowe imię nie gwarantuje konkretnego wyniku.

Moduł pomocniczy wymaga jawnego trybu AI i 24-znakowego szesnastkowego klucza, a następnie sprawdza, czy meta.access.mode ma wartość api_key. Udana odpowiedź z próby powoduje błąd niezgodności trybu dostępu zamiast cichego kontynuowania. Serwer mógł już zużyć kredyt próbny, zanim moduł wykrył tę niezgodność.

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

• Wszystkie pola pojedynczych zapytań →

Przechowuj wynik razem z informacjami, na których się opiera

Wywnioskowane powiązanie nie jest płcią zadeklarowaną przez daną osobę. Przechowuj osobno oryginalne dane wejściowe, zwrócone informacje o dopasowaniu i dane przekazane przez samą osobę. Wynik unknown jest prawidłowym wynikiem; nie zamieniaj go w swojej aplikacji na zgadywaną kategorię.

• Pola odpowiedzi i wyniki unknown →
• Dokładność i pewność wyników →
• Źródła danych i datowany profil bazy danych →

Przetwarzaj mieszaną partię i zachowaj identyfikator każdego wiersza

GenderAPI.io V2 obsługuje mieszane partie przez POST https://api.genderapi.io/api/v2/gender/batch: do 50 elementów z kluczem konta lub 10 w próbie dla adresu IP. Te przykłady wymagają klucza konta. Nadaj każdemu elementowi stałe, unikalne id i jawny tryb AI. Partia może łączyć imiona, adresy e-mail i nazwy użytkowników, a każdy element może mieć opcjonalny kontekst country.

Odczytaj każdy element w data oraz podsumowanie meta.summary. Odpowiedź HTTP 200 może zawierać błędy elementów; partia, w której wszystkie elementy zakończyły się błędem, może zwrócić odpowiedź Problem najwyższego poziomu zawierającą wyniki. Udane wyniki unknown są liczone w succeeded. index i id pozwalają przypisać każdy wynik do właściwego wiersza źródłowego.

Przy dużych zadaniach dziel dane wejściowe na grupy po maksymalnie 50 elementów i początkowo wysyłaj je po kolei. Zapisz każdą odpowiedź i jej zużycie, zanim przejdziesz do następnej grupy. Zatrzymaj się przy błędzie transportu, błędzie dostępu do konta lub niepotwierdzonym rozliczeniu i ustal stan bieżącej grupy. Równoległe wysyłanie wprowadzaj dopiero po sprawdzeniu limitów swojego konta; maksymalny rozmiar partii nie gwarantuje przepustowości.

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

• Dane wejściowe, wyniki i rozliczanie partii →

Zdecyduj, kiedy korzystać z AI

forceToGenderize jest opcjonalne dla imion, adresów e-mail i nazw użytkowników. Gdy jest włączone, pomiń ai_mode lub użyj fallback; off i always są z nim sprzeczne i zwracają 422. Dodatnie saldo początkowe wystarcza do rozpoczęcia zapytania, nawet jeśli ostateczne obciążenie obniży saldo poniżej zera.

Tryb pseudonimów może zwrócić płeć razem z name: null. Może też zwrócić wynik unknown. Ani standardowe przejście na AI, ani analiza pseudonimów nie gwarantują poprawnej odpowiedzi ani wartości innej niż null.

Moduł pomocniczy dla JavaScriptu zawsze wymaga options.ai_mode. Aby włączyć analizę pseudonimów, wyślij forceToGenderize: true razem z options: { ai_mode: 'fallback' }.

• Opcje AI i analiza pseudonimów →
• Kredyty i zużycie →

Zdecyduj, co zrobić po błędzie

Przykłady wysyłają każdą operację tylko raz. Nigdy nie ponawiają jej automatycznie: ponowne wysłanie to nowa, płatna operacja. Przekroczenie limitu czasu lub błąd połączenia oznacza, że klient nie otrzymał pełnej odpowiedzi; nie dowodzi to, że serwer przerwał przetwarzanie ani że nie pobrano kredytów.

Przechowuj zwrócony request_id i stan rozliczenia razem z rekordem swojego zadania. Obiekt błędu zachowuje odpowiedź do kontrolowanej analizy, ale może zawierać oryginalne dane wejściowe: nie zapisuj całego obiektu, odpowiedzi ani klucza API w zwykłych logach.

• Problem Details i decyzje o ponownych próbach →
• Kredyty i potwierdzenie rozliczenia →

Poznaj limit czasu fetch i kontrole odpowiedzi

Domyślny limit czasu wynosi 10 000 milisekund przez AbortSignal.timeout, łącznie z odczytem treści odpowiedzi. Przerwanie po stronie klienta nie dowodzi, że przetwarzanie lub rozliczenie zostało zatrzymane po stronie serwera. Moduł wyłącza przekierowania, odróżnia błędy HTTP od nieczytelnych odpowiedzi i nigdy nie ponawia zapytań automatycznie.

Testy z symulowanym transportem obejmują udane odpowiedzi, wyniki unknown, częściowo udane partie, zapasowe dane uwierzytelniające i błędy. Nie wymagają rzeczywistych prognoz ani operacji na kredytach; nie mierzą dostępności ani dokładności w środowisku produkcyjnym. Każde jawne polecenie demonstracyjne poniżej wysyła osobne, płatne zapytanie.

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

• Dokumentacja Node.js fetch →
• Dokumentacja Node.js AbortSignal.timeout →

Najczęściej zadawane pytania