# GenderAPI.io V2 gebruiken met Python

> Roep GenderAPI.io V2 aan vanuit Python met een voorbeeld op basis van de standaardbibliotheek. Verstuur namen, e-mailadressen en gebruikersnamen, verwerk gemengde batches en lees de velden data/meta.

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

Last reviewed: 2026-09-28

## Runtime en voorbeeld om te downloaden

Python 3.10+. Voorbeeld van een HTTP-integratie om te downloaden; geen apart gepubliceerde SDK.

- [Het voorbeeld downloaden](https://www.genderapi.io/examples/v2/genderapi_v2.py)

## Een Python-project aan de serverkant voorbereiden

Deze handleiding roept het endpoint van GenderAPI.io V2 https://api.genderapi.io/api/v2/gender aan met de API-sleutel in de Bearer-header. Gebruik Python 3.10 of hoger en download genderapi_v2.py naar uw project. Het voorbeeld gebruikt urllib.request en json uit de standaardbibliotheek van Python; er is geen pip-pakket nodig.

Stel GENDERAPI_API_KEY in de omgeving van de server in. YOUR_API_KEY in het volgende voorbeeld is geen geldige sleutel. Zet geen echte inloggegevens in bestanden onder versiebeheer, gedeelde notebooks of applicaties aan de clientkant. Het importeren van de module of het uitvoeren ervan zonder demo-opties verstuurt geen verzoek.

**De Python-omgeving configureren**

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

- [genderapi_v2.py downloaden](https://www.genderapi.io/examples/v2/genderapi_v2.py)
- [De sleutel controleren met het gratis gebruiksendpoint](https://www.genderapi.io/nl/docs/v2/authentication#environment-setup)

## Een expliciet verzoek versturen dat alleen de dataset gebruikt

Sla de volgende code op als single.py naast het gedownloade bestand en voer python3 single.py uit. De hulpmodule verstuurt type: name, value: Alice en options.ai_mode: off als JSON. De voorspelling staat in data, terwijl de informatie over het verzoek en de afschrijving in meta staat.

Een geslaagde aanroep kost 1 credit, ook bij een onbekend resultaat; de voorbeeldnaam garandeert geen voorspelling. make_item accepteert name, email of username en vereist een expliciete AI-modus. Voeg country alleen toe als u over relevante context beschikt.

Voordat er iets wordt verstuurd, vereist de hulpmodule een hexadecimale API-sleutel van 24 tekens. Daarmee wordt de notatie van de sleutel gecontroleerd, niet of de sleutel bestaat. De module weigert bovendien geslaagde antwoorden van de IP-proefperiode als onverwachte toegangsmodus; die controle vindt plaats nadat het antwoord is ontvangen en kan een al verbruikte credit van de proefperiode niet terugdraaien.

**Losse zoekopdracht in 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"])
```

- [Alle velden van losse verzoeken](https://www.genderapi.io/nl/docs/v2/request-parameters)

## Het resultaat samen met het bewijs opslaan

Een afgeleide koppeling is niet het geslacht dat iemand zelf opgeeft. Sla de oorspronkelijke invoer, het teruggegeven bewijs en wat de persoon zelf heeft opgegeven apart op. Een onbekend resultaat is een geldig resultaat en mag in uw applicatie geen geraden categorie worden.

| Veld | Gebruik |
| --- | --- |
| `data.gender / data.result_status` | Gebruik male of female alleen bij identified. Bewaar bij een onbekend resultaat de oorspronkelijke JSON-waarde null. |
| `data.name / data.match` | Controleer de teruggegeven naam en de geselecteerde kandidaat. Een match op een deel van de tekenreeks bewijst niet dat de invoer bij een persoon met die naam hoort. |
| `data.confidence / data.confidence_kind` | De betrouwbaarheidsscore staat op een schaal van 0 tot 1 of is null. observed_frequency is gebaseerd op opgeslagen frequenties; model_reported is een waarde die AI opgeeft. Evalueer drempels per soort afzonderlijk. |
| `data.source / data.sample_count` | Maak onderscheid tussen dataset, ai en none. AI-resultaten hebben geen opgeslagen steekproefgrootte. Een steekproefgrootte is geen gemeten nauwkeurigheid. |
| `meta.access.mode` | Controleer bij een integratie met een account of api_key wordt vermeld. Ontbrekende of niet-herkende sleutels kunnen anders de gedeelde IP-proefperiode gebruiken. |
| `meta.usage` | Lees charged_credits en billing_status. Een geslaagd onbekend resultaat wordt afgeschreven. Een verloren antwoord bewijst niet dat het verzoek gratis was. |

- [Antwoordvelden en onbekende resultaten](https://www.genderapi.io/nl/docs/v2/responses)
- [Nauwkeurigheid en betrouwbaarheidsscore uitgelegd](https://www.genderapi.io/nl/accuracy-methodology)
- [Gegevensbronnen en gedateerd profiel van de database](https://www.genderapi.io/nl/data-provenance)

## Een gemengde batch verwerken en de id van elke rij bewaren

GenderAPI.io V2 verwerkt gemengde batches via POST https://api.genderapi.io/api/v2/gender/batch: maximaal 50 items met een accountsleutel of 10 met de IP-proefperiode. Deze voorbeelden vereisen een accountsleutel. Geef elk item een stabiele, unieke id en een expliciete AI-modus. Een batch kan namen, e-mailadressen en gebruikersnamen combineren, en elk item kan een optionele country-context hebben.

Lees elk item in data en de samenvatting in meta.summary. Een HTTP 200-antwoord kan fouten in afzonderlijke items bevatten; een batch waarin alle items zijn mislukt, kan een Problem-antwoord op het hoogste niveau met de resultaten teruggeven. Geslaagde onbekende resultaten worden meegeteld in succeeded. Met index en id koppelt u elk resultaat aan de juiste oorspronkelijke rij.

Verdeel grotere taken in groepen van maximaal 50 items en verstuur die in het begin een voor een. Sla elk antwoord en het bijbehorende gebruik op voordat u naar de volgende groep gaat. Stop bij een transportfout, een fout bij de toegang tot het account of een onbevestigde afschrijving en zoek eerst uit wat er met de huidige groep is gebeurd. Verstuur pas parallel nadat u de limieten van uw account hebt gecontroleerd; de maximale batchgrootte garandeert geen bepaalde verwerkingscapaciteit.

**Batchzoekopdracht in 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)
```

- [Invoer, resultaten en afschrijving van batches](https://www.genderapi.io/nl/docs/v2/batch)

## Bepalen wanneer u AI gebruikt

forceToGenderize is optioneel voor namen, e-mailadressen en gebruikersnamen. Als het is ingeschakeld, laat ai_mode dan weg of gebruik fallback; off en always kunnen niet met deze optie worden gecombineerd en geven 422 terug. Een positief beginsaldo is genoeg om een verzoek te starten, ook als de uiteindelijke afschrijving het saldo negatief maakt.

De bijnaammodus kan een geslacht teruggeven samen met name: null. Ook een onbekend resultaat is mogelijk. Noch de normale AI-fallback noch de bijnaaminterpretatie garandeert een juist antwoord of een waarde anders dan null.

De hulpmodule voor Python vereist altijd ai_mode. Gebruik voor bijnaaminterpretatie make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). De module zet force_to_genderize om naar het JSON-veld forceToGenderize.

| Optie in het verzoek | Werking | Credits per geslaagde zoekopdracht |
| --- | --- | --- |
| options.ai_mode: off | Gebruikt alleen de dataset. | 1, ook bij een onbekend resultaat |
| options.ai_mode: fallback | Raadpleegt eerst de dataset en gebruikt daarna de normale AI als er geen geslacht wordt teruggegeven. Dit is de standaardwaarde voor losse verzoeken. | In totaal 1, inclusief AI-fallback |
| options.ai_mode: always | Gebruikt direct AI. | 2 |
| forceToGenderize: true | Raadpleegt eerst de dataset en laat daarna AI een persoonlijke bijnaam of alias interpreteren, ook zonder echte voornaam. | 1 voor een resultaat uit de dataset; in totaal 2 als AI wordt gebruikt |

- [AI-opties en bijnaaminterpretatie](https://www.genderapi.io/nl/docs/v2/ai-options)
- [Credits en gebruik](https://www.genderapi.io/nl/docs/v2/credits-and-usage)

## Bepalen wat u doet na een fout

De voorbeelden versturen elke bewerking één keer. Ze herhalen die nooit automatisch: opnieuw versturen is een nieuwe bewerking waarvoor een afschrijving kan gelden. Een time-out of verbindingsfout betekent dat de client geen volledig antwoord heeft ontvangen; het bewijst niet dat de server de verwerking heeft gestopt of dat er geen credits zijn afgeschreven.

Sla de teruggegeven request_id en de status van de afschrijving op bij het record van uw taak. Het foutobject bewaart het antwoord voor gecontroleerde analyse, maar kan de oorspronkelijke invoer bevatten: schrijf het volledige object, het antwoord en de API-sleutel niet naar gewone logs.

| Situatie | Beslissing in de applicatie |
| --- | --- |
| Geslaagd onbekend resultaat | Bewaar null, reason en usage. Dit is een afgerond en afgeschreven resultaat, geen mislukte rij die automatisch opnieuw moet worden geprobeerd. |
| Validatiefout 422 | Corrigeer de invoer die in de velden van Problem Details wordt genoemd voordat u een nieuw verzoek verstuurt. |
| 401 / 403 | Controleer de toegang tot het account of het beschikbare saldo. Hetzelfde verzoek opnieuw versturen lost de oorzaak niet op. |
| 429 | Respecteer de header Retry-After als die aanwezig is. Controleer de fout en de status van de afschrijving en plan de volgende poging daarna bewust. |
| Netwerkfout, time-out of onleesbaar antwoord | Registreer dat het resultaat en de afschrijving niet zijn bevestigd. Zoek de situatie uit voordat u opnieuw verstuurt; de client kan een verwerking die op de server al is afgerond niet ongedaan maken. |
| billing_status: unconfirmed | charged_credits en remaining_credits kunnen null zijn. Neem vóór een nieuwe poging contact op met support en vermeld de request_id; vervang null niet door nul credits. |
| Fouten in sommige items van een batch | Sla eerst de afgeronde items op. Controleer de mislukte items en de bijbehorende afschrijving; verstuur alleen de fouten die daarvoor in aanmerking komen opnieuw, niet de hele batch. |

- [Problem Details en beslissingen over nieuwe pogingen](https://www.genderapi.io/nl/docs/v2/errors-and-retries)
- [Credits en bevestiging van de afschrijving](https://www.genderapi.io/nl/docs/v2/credits-and-usage)

## Het netwerkgedrag van het voorbeeld kennen

De time-out van 10 seconden van urllib geldt voor blokkerende socketbewerkingen; het is geen gegarandeerde grens voor de totale duur van het verzoek. Het voorbeeld schakelt HTTP-omleidingen uit, verwerkt geslaagde JSON-antwoorden en bewaart HTTP Problem-antwoorden. Het herhaalt verzoeken nooit automatisch.

De lokale tests gebruiken gesimuleerde transportantwoorden voor geslaagde aanroepen, onbekende resultaten, gedeeltelijk geslaagde batches, toegang tot het account en fouten. Ze controleren de logica van het voorbeeld; ze meten niet de beschikbaarheid van de API in productie, de nauwkeurigheid van de voorspelling of de responstijden. Elk expliciet democommando hieronder verstuurt een eigen verzoek waarvoor een afschrijving geldt.

**Optionele expliciete demo's in Python**

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

- [Python-documentatie over urllib.request](https://docs.python.org/3/library/urllib.request.html)
- [Python-documentatie over HTTPError](https://docs.python.org/3/library/urllib.error.html)

## Waarom toont Python None in plaats van null?

De JSON-decoder van Python zet null om naar None. Bewaar de onbekende waarde: vervang die niet door een standaardgeslacht of door een betrouwbaarheidsscore van nul wanneer u het resultaat opslaat of exporteert.

## Kost een onbekend resultaat credits?

Ja. Een normale geslaagde zoekopdracht kost 1 credit, ook als gender null is. De normale AI-fallback is bij die credit inbegrepen. De modus always kost 2 credits; forceToGenderize kost 1 credit als het resultaat uit de dataset komt, of 2 als AI wordt gebruikt.

## Herhaalt het voorbeeld een mislukt verzoek?

Nee. Elk nieuw verzoek is een aparte bewerking. Controleer de fout, de resultaten van de afzonderlijke items en de status van de afschrijving voordat u besluit opnieuw te versturen. Een ontbrekend antwoord bewijst niet dat de vorige poging gratis was.

## Moet ik een pakket installeren?

Nee. Download het voorbeeld rechtstreeks vanuit deze handleiding van GenderAPI.io. Het heeft geen runtime-afhankelijkheden van externe pakketten en is geen aparte SDK die via pip of npm is gepubliceerd. Bekijk het en pas het aan voor uw applicatie; voor het contract van de API is de documentatie van GenderAPI.io V2 leidend.

## Referentiedocumentatie

- [Authenticatie in GenderAPI.io V2](https://www.genderapi.io/nl/docs/v2/authentication)
- [Antwoordvelden van V2](https://www.genderapi.io/nl/docs/v2/responses)
- [Resultaten en limieten van batches](https://www.genderapi.io/nl/docs/v2/batch)
- [Documentatie over fouten en nieuwe pogingen](https://www.genderapi.io/nl/docs/v2/errors-and-retries)