Använd GenderAPI.io V2 med Python

Förbered ett Python-projekt på serversidan

Den här guiden anropar GenderAPI.io V2-slutpunkten https://api.genderapi.io/api/v2/gender med API-nyckeln i Bearer-rubriken. Använd Python 3.10 eller senare och ladda ned genderapi_v2.py till ditt projekt. Exemplet använder urllib.request och json från Pythons standardbibliotek; det kräver inget pip-paket.

Sätt GENDERAPI_API_KEY i serverns miljö. YOUR_API_KEY i exemplet nedan är ingen giltig nyckel. Lägg inte riktiga inloggningsuppgifter i versionshanterade filer, delade notebooks eller applikationer på klientsidan. Att importera modulen eller köra den utan demoalternativ skickar ingen förfrågan.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Ladda ned genderapi_v2.py →
• Kontrollera nyckeln med den kostnadsfria slutpunkten för användning →

Skicka en uttrycklig förfrågan som bara använder datamängden

Spara koden nedan som single.py bredvid den nedladdade filen och kör sedan python3 single.py. Hjälpmodulen skickar type: name, value: Alice och options.ai_mode: off i JSON. Prediktionen läser du i data och uppgifterna om förfrågan och debiteringen i meta.

Ett lyckat anrop kostar 1 kredit, även vid ett okänt resultat; exempelnamnet garanterar ingen prediktion. make_item tar emot name, email eller username och kräver ett uttryckligt AI-läge. Lägg bara till country när du har en passande kontext.

Innan något skickas kräver hjälpmodulen en hexadecimal API-nyckel med 24 tecken. Det kontrollerar nyckelns format, inte att den finns. Dessutom avvisar modulen lyckade svar från IP-provperioden som ett avvikande åtkomstläge; kontrollen görs efter att svaret har tagits emot och kan inte ångra en provkredit som redan har förbrukats.

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

• Alla fält i enskilda förfrågningar →

Spara resultatet tillsammans med underlaget

En härledd koppling är inte det kön som en person själv uppger. Spara ursprungliga indata, det returnerade underlaget och det personen själv har angett separat. Ett okänt resultat är ett giltigt resultat och bör inte bli en gissad kategori i din applikation.

• Svarsfält och okända resultat →
• Noggrannhet och konfidens förklarade →
• Datakällor och den daterade databasprofilen →

Bearbeta en blandad batch och behåll varje rads id

GenderAPI.io V2 bearbetar blandade batchar via POST https://api.genderapi.io/api/v2/gender/batch: upp till 50 poster med en kontonyckel eller 10 med IP-provperioden. De här exemplen kräver en kontonyckel. Ge varje post ett stabilt, unikt id och ett uttryckligt AI-läge. En batch kan kombinera namn, e-postadresser och användarnamn, och varje post kan ha en valfri kontext i country.

Läs varje post i data och sammanfattningen meta.summary. Ett svar med HTTP 200 kan innehålla fel i enskilda poster; en batch där alla poster misslyckades kan ge ett problemsvar på toppnivå med resultaten. Lyckade okända resultat räknas i succeeded. Med index och id kopplar du varje resultat till rätt källrad.

Dela upp indata i stora jobb i grupper om högst 50 poster och skicka dem till att börja med en i taget. Spara varje svar och dess användning innan du går vidare till nästa grupp. Stoppa vid ett transportfel, ett fel i kontoåtkomsten eller en obekräftad debitering och klarlägg läget för den aktuella gruppen. Inför parallella sändningar först när du har kontrollerat ditt kontos gränser; den största batchstorleken garanterar ingen genomströmning.

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)

• Indata, resultat och debitering för batchar →

Bestäm när AI ska användas

forceToGenderize är valfritt för namn, e-postadresser och användarnamn. När det är aktiverat utelämnar du ai_mode eller använder fallback; off och always kan inte kombineras med det och ger 422. Ett positivt startsaldo räcker för att starta en förfrågan, även om den slutliga debiteringen gör saldot negativt.

Smeknamnsläget kan returnera ett kön tillsammans med name: null. Det kan också ge ett okänt resultat. Varken vanlig AI-reserv eller tolkning av smeknamn garanterar ett korrekt svar eller ett värde som inte är null.

Hjälpmodulen för Python kräver alltid ai_mode. För tolkning av smeknamn använder du make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Modulen omvandlar force_to_genderize till JSON-fältet forceToGenderize.

• AI-alternativ och tolkning av smeknamn →
• Krediter och användning →

Bestäm vad som händer efter ett fel

Exemplen skickar varje åtgärd bara en gång. De upprepar den aldrig automatiskt: att skicka igen är en ny åtgärd som debiteras. En överskriden tidsgräns eller ett anslutningsfel betyder att klienten inte fick något fullständigt svar; det visar varken att servern avbröt bearbetningen eller att inga krediter drogs.

Spara det returnerade request_id och debiteringsstatusen tillsammans med posten för ditt jobb. Felobjektet behåller svaret för en kontrollerad analys men kan innehålla de ursprungliga indata: skriv varken hela objektet, svaret eller API-nyckeln till vanliga loggar.

• Problem Details och beslut om nya försök →
• Krediter och bekräftad debitering →

Känn till exemplets nätverksbeteende

Tidsgränsen på 10 sekunder i urllib gäller blockerande socketåtgärder; den är ingen garanterad gräns för förfrågans totala tid. Exemplet stänger av HTTP-omdirigeringar, tolkar lyckade JSON-svar och behåller HTTP-problemsvar. Det gör aldrig om förfrågningar automatiskt.

Lokala tester använder simulerade transportsvar för lyckade anrop, okända resultat, delvis lyckade batchar, kontoåtkomst och fel. De kontrollerar exemplets styrlogik; de mäter varken API:ets tillgänglighet i produktion, inferensens noggrannhet eller svarstider. Varje uttryckligt demokommando nedan skickar en egen förfrågan som debiteras.

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

• Python-dokumentation om urllib.request →
• Python-dokumentation om HTTPError →

Vanliga frågor