Použití GenderAPI.io V2 s Pythonem

Nastavte projekt v Pythonu na straně serveru

Tento průvodce volá endpoint GenderAPI.io V2 https://api.genderapi.io/api/v2/gender s API klíčem jako tokenem Bearer. Použijte Python 3.10 nebo novější a stáhněte si genderapi_v2.py do svého projektu. Příklad používá urllib.request a json ze standardní knihovny Pythonu; žádný balíček pip není potřeba.

Nastavte GENDERAPI_API_KEY v prostředí serveru. YOUR_API_KEY v příkladu níže není platný klíč. Skutečné přihlašovací údaje neukládejte do souborů ve správě verzí, do sdílených notebooků ani do aplikací na straně klienta. Import modulu ani jeho spuštění bez volby pro ukázku neodešle žádný požadavek.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Stáhnout genderapi_v2.py →
• Ověřte klíč pomocí bezplatného endpointu pro využití →

Odešlete jeden výslovný požadavek pouze s datovou sadou

Uložte níže uvedený kód jako single.py vedle staženého souboru a spusťte python3 single.py. Pomocný modul odešle type: name, value: Alice a options.ai_mode: off jako JSON. Odhad čtěte v data a údaje o požadavku a účtování v meta.

Úspěšné volání stojí 1 kredit, i když je výsledek neznámý; ukázkové jméno nezaručuje odhad. make_item přijímá name, email nebo username a vyžaduje výslovný režim AI. country přidejte jen tehdy, když máte relevantní kontext.

Před odesláním pomocný modul vyžaduje hexadecimální API klíč o 24 znacích. Tím se kontroluje formát, nikoli to, zda klíč existuje. Modul také odmítá úspěšné odpovědi ze zkušebního režimu podle IP, protože režim přístupu neodpovídá; tato kontrola proběhne až po odpovědi a nemůže vrátit kredit účtovaný ve zkušebním režimu.

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"])

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

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)

• 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 Python vždy vyžaduje ai_mode. Chcete-li povolit analýzu přezdívek, použijte make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Pomocný modul převede force_to_genderize na pole JSON forceToGenderize.

• 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í →

Jak příklad zachází s přenosem

Časový limit 10 sekund v urllib platí pro blokující operace socketu a není zaručenou lhůtou pro celkové trvání požadavku. Příklad vypíná přesměrování HTTP, zpracovává úspěšné odpovědi JSON a zachovává odpovědi HTTP typu Problem. Nikdy automaticky neopakuje požadavky.

Místní testy používají syntetické odpovědi přenosu pro úspěšná volání, neznámé výsledky, částečně úspěšné dávky, přístup k účtu a chyby. Ověřují logiku příkladu; neměří dostupnost API v provozu, přesnost odhadů ani latenci v produkčním prostředí. Každý volitelný příkaz ukázky níže odešle vlastní požadavek, který se účtuje.

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

• Dokumentace Pythonu: urllib.request →
• Dokumentace Pythonu: HTTPError →

Časté dotazy