# Använd GenderAPI.io V2 med Python

> Anropa GenderAPI.io V2 från Python med ett exempel som bygger på standardbiblioteket. Skicka namn, e-postadresser och användarnamn, bearbeta blandade batchar och läs fälten data/meta.

Canonical HTML: https://www.genderapi.io/sv/integrations/python

Last reviewed: 2026-09-28

## Körmiljö och exempel att ladda ned

Python 3.10+. HTTP-integrationsexempel att ladda ned; inget separat publicerat SDK.

- [Ladda ned exemplet](https://www.genderapi.io/examples/v2/genderapi_v2.py)

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

**Konfigurera Python-miljön**

```bash
python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"
```

- [Ladda ned genderapi_v2.py](https://www.genderapi.io/examples/v2/genderapi_v2.py)
- [Kontrollera nyckeln med den kostnadsfria slutpunkten för användning](https://www.genderapi.io/sv/docs/v2/authentication#environment-setup)

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

**Enskild sökning i Python**

```python
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](https://www.genderapi.io/sv/docs/v2/request-parameters)

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

| Fält | Användning |
| --- | --- |
| `data.gender / data.result_status` | Använd male eller female bara vid identified. Behåll det inbyggda JSON-värdet null vid ett okänt resultat. |
| `data.name / data.match` | Granska det returnerade namnet och den valda kandidaten. En träff på en delsträng visar inte att indata tillhör en person med det förnamnet. |
| `data.confidence / data.confidence_kind` | Konfidensen ligger på en skala från 0 till 1 eller är null. observed_frequency bygger på lagrade frekvenser; model_reported är ett AI-värde. Utvärdera tröskelvärden separat för varje typ. |
| `data.source / data.sample_count` | Skilj mellan dataset, ai och none. AI-resultat har ingen lagrad urvalsstorlek. En urvalsstorlek är inget uppmätt noggrannhetsvärde. |
| `meta.access.mode` | Kontrollera att api_key rapporteras i en kontointegration. Nycklar som saknas eller inte känns igen kan i stället använda den delade IP-provperioden. |
| `meta.usage` | Läs charged_credits och billing_status. Ett lyckat okänt resultat debiteras. Ett förlorat svar visar inte att förfrågan var kostnadsfri. |

- [Svarsfält och okända resultat](https://www.genderapi.io/sv/docs/v2/responses)
- [Noggrannhet och konfidens förklarade](https://www.genderapi.io/sv/accuracy-methodology)
- [Datakällor och den daterade databasprofilen](https://www.genderapi.io/sv/data-provenance)

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

**Batchsökning i Python**

```python
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](https://www.genderapi.io/sv/docs/v2/batch)

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

| Alternativ i förfrågan | Beteende | Krediter för en lyckad sökning |
| --- | --- | --- |
| options.ai_mode: off | Använd bara datamängden. | 1, även för ett okänt resultat |
| options.ai_mode: fallback | Kontrollera datamängden först och använd sedan vanlig AI om inget kön returneras. Detta är standard för enskilda förfrågningar. | Totalt 1, inklusive AI-reserv |
| options.ai_mode: always | Använd AI direkt. | 2 |
| forceToGenderize: true | Kontrollera datamängden först och låt sedan AI tolka ett personligt smeknamn eller alias, även utan ett riktigt förnamn. | 1 för ett resultat som fastställs i datamängden; totalt 2 om AI används |

- [AI-alternativ och tolkning av smeknamn](https://www.genderapi.io/sv/docs/v2/ai-options)
- [Krediter och användning](https://www.genderapi.io/sv/docs/v2/credits-and-usage)

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

| Situation | Applikationens beslut |
| --- | --- |
| Lyckat okänt resultat | Behåll null, reason och usage. Det är ett avslutat resultat som debiteras och ingen misslyckad rad för ett automatiskt nytt försök. |
| Valideringsfel 422 | Rätta de indata som anges i fälten i Problem Details innan du skickar en ny förfrågan. |
| 401 / 403 | Kontrollera kontoåtkomsten eller det tillgängliga saldot. Att skicka samma förfrågan igen åtgärdar inte orsaken. |
| 429 | Respektera rubriken Retry-After om den finns. Kontrollera felet och debiteringsstatusen och planera sedan nästa försök medvetet. |
| Nätverksfel, överskriden tidsgräns eller oläsbart svar | Registrera att resultatet och debiteringen är obekräftade. Klarlägg läget innan du skickar igen; klienten kan inte ångra en bearbetning som redan har slutförts på servern. |
| billing_status: unconfirmed | charged_credits och remaining_credits kan vara null. Kontakta supporten med request_id innan du gör ett nytt försök; ersätt inte null med noll krediter. |
| Fel i vissa poster i en batch | Spara de slutförda posterna först. Granska de misslyckade posterna och deras debitering; skicka bara om de felen, inte hela batchen. |

- [Problem Details och beslut om nya försök](https://www.genderapi.io/sv/docs/v2/errors-and-retries)
- [Krediter och bekräftad debitering](https://www.genderapi.io/sv/docs/v2/credits-and-usage)

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

**Valfria uttryckliga demor i Python**

```bash
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](https://docs.python.org/3/library/urllib.request.html)
- [Python-dokumentation om HTTPError](https://docs.python.org/3/library/urllib.error.html)

## Varför visar Python None i stället för null?

Pythons JSON-avkodare omvandlar null till None. Behåll det okända värdet: ersätt det varken med ett standardkön eller med konfidensen noll när du sparar eller exporterar resultatet.

## Förbrukar ett okänt resultat krediter?

Ja. En lyckad vanlig sökning kostar 1 kredit, även när gender är null. Den vanliga AI-reserven ingår i den krediten. Läget always kostar 2 krediter; forceToGenderize kostar 1 kredit om datamängden ger resultatet, eller 2 om AI används.

## Gör exemplet om en misslyckad förfrågan?

Nej. Varje ny förfrågan är en egen åtgärd. Granska felet, resultaten för de enskilda posterna och debiteringsstatusen innan du bestämmer dig för att skicka igen. Ett uteblivet svar visar inte att det tidigare försöket var kostnadsfritt.

## Måste jag installera ett paket?

Nej. Ladda ned exemplet direkt från den här guiden hos GenderAPI.io. Det har inga körberoenden till externa paket och är inget separat SDK som publiceras i pip eller npm. Granska det och anpassa det till din applikation; för API-kontraktet gäller dokumentationen för GenderAPI.io V2.

## Referensdokumentation

- [Autentisering i GenderAPI.io V2](https://www.genderapi.io/sv/docs/v2/authentication)
- [Svarsfält i V2](https://www.genderapi.io/sv/docs/v2/responses)
- [Batchresultat och gränser](https://www.genderapi.io/sv/docs/v2/batch)
- [Dokumentation om fel och nya försök](https://www.genderapi.io/sv/docs/v2/errors-and-retries)