Brug GenderAPI.io V2 med Python

Forbered et Python-projekt på serversiden

Denne guide kalder endpointet i GenderAPI.io V2 https://api.genderapi.io/api/v2/gender med API-nøglen i Bearer-headeren. Brug Python 3.10 eller nyere, og download genderapi_v2.py til dit projekt. Eksemplet bruger urllib.request og json fra Pythons standardbibliotek; der kræves ingen pip-pakke.

Angiv GENDERAPI_API_KEY i serverens miljø. YOUR_API_KEY i det følgende eksempel er ikke en gyldig nøgle. Læg ikke rigtige loginoplysninger i filer under versionsstyring, delte notebooks eller applikationer på klientsiden. At importere modulet eller køre det uden demo-indstillinger sender ingen forespørgsel.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Download genderapi_v2.py →
• Kontrollér nøglen med det gratis endpoint for forbrug →

Send en eksplicit forespørgsel, der kun bruger datasættet

Gem følgende kode som single.py ved siden af den downloadede fil, og kør python3 single.py. Hjælpemodulet sender type: name, value: Alice og options.ai_mode: off som JSON. Forudsigelsen står i data, mens oplysningerne om forespørgslen og opkrævningen står i meta.

Et gennemført kald koster 1 kredit, også ved et ukendt resultat, og eksempelnavnet garanterer ikke en forudsigelse. make_item accepterer name, email eller username og kræver en eksplicit AI-tilstand. Tilføj kun country, hvis du har en relevant kontekst.

Før noget sendes, kræver hjælpemodulet en hexadecimal API-nøgle på 24 tegn. Det kontrollerer nøglens format, ikke om nøglen findes. Modulet afviser desuden gennemførte svar fra IP-prøveadgangen som en uventet adgangstilstand. Den kontrol sker, efter at svaret er modtaget, og kan ikke tilbageføre en kredit fra prøveadgangen, der allerede er brugt.

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

• Alle felter i enkeltforespørgsler →

Gem resultatet sammen med evidensen

En udledt sammenhæng er ikke det køn, en person selv har oplyst. Gem det oprindelige input, den returnerede evidens og det, personen selv har oplyst, hver for sig. Et ukendt resultat er et gyldigt resultat og bør ikke blive til en gættet kategori i din applikation.

• Svarfelter og ukendte resultater →
• Nøjagtighed og konfidens forklaret →
• Datakilder og databasens daterede profil →

Behandl en blandet batch, og bevar id'et for hver række

GenderAPI.io V2 behandler blandede batches via POST https://api.genderapi.io/api/v2/gender/batch: op til 50 elementer med en kontonøgle eller 10 med IP-prøveadgangen. Disse eksempler kræver en kontonøgle. Giv hvert element et stabilt, unikt id og en eksplicit AI-tilstand. En batch kan kombinere navne, e-mailadresser og brugernavne, og hvert element kan have en valgfri country-kontekst.

Læs hvert element i data og oversigten i meta.summary. Et HTTP 200-svar kan indeholde fejl i enkelte elementer, og en batch, hvor alle elementer er mislykkedes, kan returnere et Problem-svar på øverste niveau med resultaterne. Gennemførte ukendte resultater tælles med i succeeded. Med index og id knytter du hvert resultat til den rigtige oprindelige række.

Del større opgaver op i grupper på højst 50 elementer, og send dem i begyndelsen én ad gangen. Gem hvert svar og det tilhørende forbrug, før du går videre til næste gruppe. Stop ved en transportfejl, en fejl i adgangen til kontoen eller en ubekræftet opkrævning, og find først ud af, hvad der skete med den aktuelle gruppe. Send først parallelt, når du har kontrolleret din kontos grænser. Den maksimale batchstørrelse garanterer ikke en bestemt behandlingskapacitet.

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)

• Input, resultater og opkrævning for batches →

Beslut, hvornår AI skal bruges

forceToGenderize er valgfrit for navne, e-mailadresser og brugernavne. Når det er slået til, skal du udelade ai_mode eller bruge fallback. off og always kan ikke kombineres med denne indstilling og returnerer 422. En positiv startsaldo er nok til at starte en forespørgsel, også selvom den endelige opkrævning gør saldoen negativ.

Kaldenavnstilstanden kan returnere et køn sammen med name: null. Den kan også give et ukendt resultat. Hverken den almindelige automatiske AI-fallback eller fortolkningen af kaldenavne garanterer et korrekt svar eller en værdi, der ikke er null.

Hjælpemodulet til Python kræver altid ai_mode. Brug make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True) til fortolkning af kaldenavne. Modulet omsætter force_to_genderize til JSON-feltet forceToGenderize.

• AI-indstillinger og fortolkning af kaldenavne →
• Kreditter og forbrug →

Beslut, hvad du gør efter en fejl

Eksemplerne sender hver handling én gang. De gentager den aldrig automatisk: At sende igen er en ny handling, som kan blive opkrævet. En timeout eller en forbindelsesfejl betyder, at klienten ikke har modtaget et fuldstændigt svar. Det beviser ikke, at serveren har stoppet behandlingen, eller at der ikke er opkrævet kreditter.

Gem det returnerede request_id og opkrævningens status sammen med posten for din opgave. Fejlobjektet bevarer svaret til kontrolleret analyse, men kan indeholde det oprindelige input: Skriv ikke hele objektet, svaret og API-nøglen i almindelige logfiler.

• Problem Details og beslutninger om nye forsøg →
• Kreditter og bekræftelse af opkrævningen →

Kend eksemplets netværksadfærd

urllibs timeout på 10 sekunder gælder for blokerende socket-handlinger og er ikke en garanteret grænse for forespørgslens samlede varighed. Eksemplet slår HTTP-omdirigeringer fra, behandler gennemførte JSON-svar og bevarer HTTP Problem-svar. Det gentager aldrig forespørgsler automatisk.

De lokale test bruger simulerede transportsvar for gennemførte kald, ukendte resultater, delvist gennemførte batches, adgang til kontoen og fejl. De kontrollerer eksemplets logik, men måler ikke API'ets tilgængelighed i produktion, forudsigelsens nøjagtighed eller svartiderne. Hver eksplicit demokommando nedenfor sender sin egen forespørgsel, som bliver opkrævet.

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 →

Ofte stillede spørgsmål