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

> Wywołuj GenderAPI.io V2 z Node.js za pomocą natywnego fetch. Pobierz moduł ES do pojedynczych zapytań i mieszanych partii, odczytu odpowiedzi data/meta i obsługi błędów związanych z kredytami.

Canonical HTML: https://www.genderapi.io/pl/integrations/javascript

Last reviewed: 2026-09-28

## Środowisko uruchomieniowe i przykład do pobrania

Node.js 22+. Przykład integracji HTTP do pobrania; nie jest to osobno publikowane SDK.

- [Pobierz przykład](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)

## 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.

**Skonfiguruj środowisko Node.js**

```bash
node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"
```

- [Pobierz genderapi-v2.mjs](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [Sprawdź klucz za pomocą bezpłatnego endpointu zużycia](https://www.genderapi.io/pl/docs/v2/authentication#environment-setup)

## 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ść.

**Pojedyncze wyszukiwanie w Node.js**

```javascript
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ń](https://www.genderapi.io/pl/docs/v2/request-parameters)

## 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ę.

| Pole | Jak z niego korzystać |
| --- | --- |
| `data.gender / data.result_status` | Używaj male lub female tylko wtedy, gdy wynik ma status identified. Gdy wynik jest unknown, zachowaj natywną wartość null z JSON. |
| `data.name / data.match` | Sprawdź zwrócone imię i wybranego kandydata. Dopasowanie fragmentu nie dowodzi, że dane wejściowe należą do osoby o tym imieniu. |
| `data.confidence / data.confidence_kind` | Pewność jest wyrażona w skali 0–1 albo ma wartość null. observed_frequency wynika z zapisanych liczb wystąpień; model_reported to wynik podany przez AI. Progi oceniaj osobno dla każdego rodzaju. |
| `data.source / data.sample_count` | Rozróżniaj dataset, ai i none. Wyniki AI nie mają zapisanej liczby próbek. Liczba próbek nie jest zmierzoną dokładnością. |
| `meta.access.mode` | W integracji z kontem sprawdź, czy wartość to api_key. Brakujący lub nierozpoznany klucz może zamiast tego korzystać ze wspólnej próby dla adresu IP. |
| `meta.usage` | Odczytaj charged_credits i billing_status. Udany wynik unknown jest płatny. Utrata odpowiedzi nie oznacza, że zapytanie było bezpłatne. |

- [Pola odpowiedzi i wyniki unknown](https://www.genderapi.io/pl/docs/v2/responses)
- [Dokładność i pewność wyników](https://www.genderapi.io/pl/accuracy-methodology)
- [Źródła danych i datowany profil bazy danych](https://www.genderapi.io/pl/data-provenance)

## 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.

**Wyszukiwanie w partii w Node.js**

```javascript
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](https://www.genderapi.io/pl/docs/v2/batch)

## 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' }.

| Opcja zapytania | Działanie | Kredyty za udane wyszukiwanie |
| --- | --- | --- |
| options.ai_mode: off | Korzysta tylko ze zbioru danych. | 1, także przy wyniku unknown |
| options.ai_mode: fallback | Najpierw sprawdza zbiór danych, a gdy nie zwróci on płci, korzysta ze standardowej AI. To ustawienie domyślne dla pojedynczych zapytań. | Łącznie 1, łącznie z przejściem na AI |
| options.ai_mode: always | Od razu korzysta z AI. | 2 |
| forceToGenderize: true | Najpierw sprawdza zbiór danych, a potem pozwala AI zinterpretować osobisty pseudonim lub alias, nawet bez prawdziwego imienia. | 1 za wynik rozstrzygnięty w zbiorze danych; łącznie 2, jeśli użyta zostanie AI |

- [Opcje AI i analiza pseudonimów](https://www.genderapi.io/pl/docs/v2/ai-options)
- [Kredyty i zużycie](https://www.genderapi.io/pl/docs/v2/credits-and-usage)

## 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.

| Sytuacja | Decyzja aplikacji |
| --- | --- |
| Udany wynik unknown | Zachowaj null, reason i usage. To zakończony, płatny wynik, a nie nieudany wiersz do automatycznego ponowienia. |
| Błąd walidacji 422 | Popraw dane wejściowe wskazane w polach Problem Details, zanim wyślesz nowe zapytanie. |
| 401 / 403 | Sprawdź dostęp do konta lub dostępne kredyty. Wielokrotne wysyłanie tego samego zapytania nie usunie przyczyny. |
| 429 | Jeśli nagłówek Retry-After jest obecny, zastosuj się do niego. Sprawdź błąd i stan rozliczenia, a następnie świadomie zaplanuj kolejną próbę. |
| Błąd sieci, przekroczenie limitu czasu lub nieczytelna odpowiedź | Odnotuj, że wynik i obciążenie nie są potwierdzone. Przed ponownym wysłaniem ustal stan; klient nie może cofnąć przetwarzania zakończonego już po stronie serwera. |
| billing_status: unconfirmed | charged_credits i remaining_credits mogą mieć wartość null. Przed kolejną próbą skontaktuj się z pomocą techniczną, podając request_id; nie zastępuj null zerem. |
| Błędy niektórych elementów partii | Najpierw zapisz zakończone elementy. Sprawdź nieudane elementy i ich rozliczenie; wyślij ponownie tylko te błędy, a nie całą partię. |

- [Problem Details i decyzje o ponownych próbach](https://www.genderapi.io/pl/docs/v2/errors-and-retries)
- [Kredyty i potwierdzenie rozliczenia](https://www.genderapi.io/pl/docs/v2/credits-and-usage)

## 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.

**Opcjonalne jawne demonstracje w Node.js**

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

- [Dokumentacja Node.js fetch](https://nodejs.org/api/globals.html#fetch)
- [Dokumentacja Node.js AbortSignal.timeout](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay)

## Czy mogę wkleić ten kod do JavaScriptu wykonywanego w przeglądarce?

Pozostaw go na swoim serwerze. Kod aplikacji wykonywany w przeglądarce ujawnia klucz API jej użytkownikom. Z przeglądarki wywołuj własny uwierzytelniony backend i pozwól mu wysłać zapytanie do GenderAPI.io.

## Czy wynik unknown zużywa kredyty?

Tak. Udane standardowe wyszukiwanie kosztuje 1 kredyt, nawet gdy gender ma wartość null. Standardowe przejście na AI mieści się w tym kredycie. Tryb always kosztuje 2 kredyty; forceToGenderize kosztuje 1 kredyt, gdy zbiór danych rozstrzygnie zapytanie, albo 2, gdy użyta zostanie AI.

## Czy ten przykład ponawia nieudane zapytanie?

Nie. Każde nowe zapytanie jest odrębną operacją. Zanim zdecydujesz o ponownym wysłaniu, sprawdź błąd, wyniki poszczególnych elementów i stan rozliczenia. Brak odpowiedzi nie dowodzi, że poprzednia próba była bezpłatna.

## Czy muszę instalować pakiet?

Nie. Pobierz przykład bezpośrednio z tego przewodnika GenderAPI.io. Nie ma zależności wykonawczych od zewnętrznych pakietów i nie jest osobno publikowanym SDK w pip ani npm. Przejrzyj go i dostosuj do swojej aplikacji; punktem odniesienia dla kontraktu API pozostaje dokumentacja GenderAPI.io V2.

## Dokumentacja referencyjna

- [Uwierzytelnianie w GenderAPI.io V2](https://www.genderapi.io/pl/docs/v2/authentication)
- [Pola odpowiedzi V2](https://www.genderapi.io/pl/docs/v2/responses)
- [Wyniki i limity partii](https://www.genderapi.io/pl/docs/v2/batch)
- [Dokumentacja błędów i ponownych prób](https://www.genderapi.io/pl/docs/v2/errors-and-retries)