# Korzystanie z GenderAPI.io V2 w Pythonie

> Wywołuj GenderAPI.io V2 z Pythona za pomocą przykładu opartego na bibliotece standardowej. Wysyłaj imiona, adresy e-mail i nazwy użytkowników, przetwarzaj mieszane partie i odczytuj pola data/meta.

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

Last reviewed: 2026-09-28

## Środowisko uruchomieniowe i przykład do pobrania

Python 3.10+. Przykład integracji HTTP do pobrania; nie jest to osobno publikowane SDK.

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

## Przygotuj projekt Python po stronie serwera

Ten przewodnik wywołuje endpoint GenderAPI.io V2 https://api.genderapi.io/api/v2/gender z kluczem API w nagłówku Bearer. Użyj Pythona 3.10 lub nowszego i pobierz genderapi_v2.py do swojego projektu. Przykład korzysta z urllib.request i json z biblioteki standardowej Pythona; nie wymaga żadnego pakietu pip.

Ustaw GENDERAPI_API_KEY w środowisku swojego serwera. YOUR_API_KEY w poniższym przykładzie nie jest prawidłowym kluczem. Nie umieszczaj prawdziwych danych uwierzytelniających w plikach pod kontrolą wersji, współdzielonych notatnikach ani aplikacjach po stronie klienta. Import modułu lub uruchomienie go bez opcji demonstracyjnej nie wysyła żadnego zapytania.

**Skonfiguruj środowisko Python**

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

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

## Wyślij jawne zapytanie tylko do zbioru danych

Zapisz poniższy kod jako single.py obok pobranego pliku, a następnie uruchom python3 single.py. Moduł pomocniczy wysyła w JSON type: name, value: Alice i options.ai_mode: off. Prognozę odczytasz z data, a informacje o zapytaniu i rozliczeniu z meta.

Udane wywołanie kosztuje 1 kredyt, także przy wyniku unknown; przykładowe imię nie gwarantuje prognozy. make_item przyjmuje name, email lub username i wymaga jawnego trybu AI. Dodawaj country tylko wtedy, gdy masz odpowiedni kontekst.

Przed wysłaniem moduł pomocniczy wymaga 24-znakowego szesnastkowego klucza API. Sprawdza to format klucza, a nie jego istnienie. Odrzuca też udane odpowiedzi z próby dla adresu IP jako niezgodność trybu dostępu; ta kontrola następuje po otrzymaniu odpowiedzi i nie może cofnąć już zużytego kredytu próbnego.

**Pojedyncze wyszukiwanie w Pythonie**

```python
from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])
```

- [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 Pythonie**

```python
from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)
```

- [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 Pythona zawsze wymaga ai_mode. Aby włączyć analizę pseudonimów, użyj make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Moduł zamienia force_to_genderize na pole JSON forceToGenderize.

| 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 zachowanie sieciowe tego przykładu

10-sekundowy limit czasu urllib dotyczy blokujących operacji na gniazdach; nie jest gwarantowanym limitem całkowitego czasu zapytania. Przykład wyłącza przekierowania HTTP, analizuje udane odpowiedzi JSON i zachowuje odpowiedzi HTTP Problem. Nigdy nie ponawia zapytań automatycznie.

Testy lokalne używają symulowanych odpowiedzi transportu dla sukcesów, wyników unknown, częściowo udanych partii, dostępu do konta i błędów. Sprawdzają logikę kontrolną przykładu; nie mierzą dostępności API w środowisku produkcyjnym, dokładności inferencji ani opóźnień. Każde jawne polecenie demonstracyjne poniżej wysyła osobne, płatne zapytanie.

**Opcjonalne jawne demonstracje w Pythonie**

```bash
python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch
```

- [Dokumentacja Python urllib.request](https://docs.python.org/3/library/urllib.request.html)
- [Dokumentacja Python HTTPError](https://docs.python.org/3/library/urllib.error.html)

## Dlaczego Python pokazuje None zamiast null?

Dekoder JSON w Pythonie zamienia null na None. Zachowaj tę nieznaną wartość: nie zamieniaj jej na domyślną płeć ani na zerową pewność podczas zapisywania lub eksportowania wyniku.

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