Korzystanie z GenderAPI.io V2 w Pythonie

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.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Pobierz genderapi_v2.py →
• Sprawdź klucz za pomocą bezpłatnego endpointu zużycia →

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.

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ń →

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.

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 →

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.

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

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

• Dokumentacja Python urllib.request →
• Dokumentacja Python HTTPError →

Najczęściej zadawane pytania