Bruk GenderAPI.io V2 med Python

Konfigurer et Python-prosjekt på serversiden

Denne veiledningen kaller endepunktet https://api.genderapi.io/api/v2/gender i GenderAPI.io V2 med en API-nøkkel som Bearer-token. Bruk Python 3.10 eller nyere, og last ned genderapi_v2.py til prosjektet ditt. Eksemplet bruker urllib.request og json fra standardbiblioteket i Python; ingen pip-pakke er nødvendig.

Angi GENDERAPI_API_KEY i miljøet på serveren. YOUR_API_KEY i eksemplet nedenfor er ikke en gyldig nøkkel. Hold ekte påloggingsopplysninger utenfor filer som legges inn i versjonskontroll, notatbøker du deler, og applikasjoner på klientsiden. Å importere modulen eller kjøre den uten et demoalternativ sender ingen forespørsel.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Last ned genderapi_v2.py →
• Kontroller nøkkelen med det gratis endepunktet for forbruk →

Send én eksplisitt forespørsel som bare bruker datasettet

Lagre koden nedenfor som single.py ved siden av den nedlastede filen, og kjør python3 single.py. Hjelpemodulen sender type: name, value: Alice og options.ai_mode: off som JSON. Les estimatet i data og opplysningene om forespørselen og belastningen i meta.

Et vellykket kall bruker 1 kreditt, også ved et ukjent resultat; eksempelnavnet garanterer ikke en prediksjon. make_item godtar name, email eller username og krever en eksplisitt KI-modus. Legg bare til country når du har relevant kontekst.

Før noe sendes, krever hjelpemodulen en heksadesimal API-nøkkel på 24 tegn. Dette kontrollerer formatet, ikke om nøkkelen finnes. Modulen avviser også vellykkede svar fra IP-prøveperioden fordi tilgangsmodusen ikke stemmer; denne kontrollen skjer etter svaret og kan ikke gjøre om en belastning i prøveperioden.

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 felt i enkeltforespørsler →

Lagre resultatet sammen med grunnlaget

En utledet tilknytning er ikke det kjønnet en person selv har oppgitt. Lagre de opprinnelige inndataene, grunnlaget som ble returnert, og det personen selv har oppgitt, hver for seg. Et ukjent resultat er et gyldig resultat og bør ikke bli en gjettet kategori i applikasjonen din.

• Svarfelt og ukjente resultater →
• Nøyaktighet og konfidens forklart →
• Datakilder og den daterte profilen til datasettet →

Behandle en blandet samleforespørsel og behold id-en for hver rad

GenderAPI.io V2 bruker POST https://api.genderapi.io/api/v2/gender/batch for blandede samleforespørsler: høyst 50 elementer med en kontonøkkel eller 10 i IP-prøveperioden. Disse eksemplene krever en kontonøkkel. Gi hvert element en stabil, unik id og en eksplisitt KI-modus. En samleforespørsel kan kombinere navn, e-postadresser og brukernavn, og hvert element kan ha en valgfri landkontekst.

Les hvert element i data og sammendraget i meta.summary. Et HTTP 200-svar kan inneholde feil for enkeltelementer; en samleforespørsel der alle elementene mislyktes, kan gi et Problem-svar på øverste nivå som inneholder resultatene. Vellykkede ukjente resultater telles som succeeded. Med den opprinnelige index og id kan du knytte hvert utfall til riktig kilderad.

Ved større jobber deler du inndataene i grupper på høyst 50 og sender dem først etter hverandre. Lagre hvert svar og forbruket før du går videre. Stopp ved feil i overføringen, feil med kontoen eller en belastning som ikke er bekreftet, og stem av den gjeldende gruppen. Legg bare til parallelle forespørsler etter at du har kontrollert grensene for kontoen din; den største tillatte samleforespørselen er ingen garanti for kapasitet.

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)

• Inndata, resultater og belastning for samleforespørsler →

Bestem når KI skal brukes

forceToGenderize er valgfritt for navn, e-postadresser og brukernavn. Når det er aktivert, utelater du ai_mode eller bruker fallback; off og always kan ikke kombineres med dette alternativet og gir 422. En positiv startsaldo er nok til å starte en forespørsel, selv om den endelige belastningen gjør saldoen negativ.

Kallenavnmodus kan returnere et kjønn sammen med name: null. Den kan også gi et ukjent resultat. Verken vanlig KI-reserve eller tolkning av kallenavn garanterer et riktig svar eller en verdi som ikke er null.

Denne hjelpemodulen for Python krever alltid ai_mode. For å tillate tolkning av kallenavn bruker du make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Hjelpemodulen gjør force_to_genderize om til JSON-feltet forceToGenderize.

• KI-alternativer og tolkning av kallenavn →
• Kreditter og forbruk →

Bestem hva du gjør etter en feil

Eksemplene sender hver operasjon én gang. De prøver ikke på nytt automatisk: En ny innsending er en ny operasjon som belastes. Et tidsavbrudd eller en tilkoblingsfeil betyr at klienten ikke fikk et fullstendig svar; det beviser ikke at serveren stoppet, eller at ingen kreditter ble belastet.

Lagre forespørsels-ID-en og belastningsstatusen som returneres, sammen med posten for jobben. Feilobjektet beholder svaret slik at det kan undersøkes kontrollert, men det kan inneholde de opprinnelige inndataene; ikke skriv hele objektet, svaret eller API-nøkkelen til vanlige logger.

• Problem Details og beslutninger om nye forsøk →
• Kreditter og bekreftelse av belastningen →

Forstå hvordan eksemplet håndterer overføringen

Tidsavbruddet på 10 sekunder i urllib gjelder blokkerende socket-operasjoner og er ingen garantert frist for den totale varigheten av hele forespørselen. Eksemplet slår av HTTP-omdirigeringer, tolker vellykkede JSON-svar og beholder HTTP-svar av typen Problem. Det prøver aldri på nytt automatisk.

Lokale tester bruker syntetiske overføringssvar for vellykkede kall, ukjente resultater, delvis vellykkede samleforespørsler, kontotilgang og feil. De kontrollerer logikken i eksemplet; de måler ikke tilgjengeligheten til API-et i drift, nøyaktigheten til prediksjonene eller svartidene i produksjon. Hver valgfri demokommando nedenfor sender sin egen forespørsel, som belastes.

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

• Python-dokumentasjon: urllib.request →
• Python-dokumentasjon: HTTPError →

Ofte stilte spørsmål