# Python ile GenderAPI V2 entegrasyonu

> Python standart kütüphanesiyle isim, e-posta ve kullanıcı adı sorgulayın; toplu sonuçları, bilinmeyen değerleri ve kredi kullanımını yönetin.

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

Last reviewed: 2026-09-27

## Çalışma ortamı ve örnek dosya

Python 3.10+. İndirilebilir HTTP yardımcı dosyasıdır; ayrı yayımlanmış SDK paketi değildir.

- [Örneği indir](https://www.genderapi.io/examples/v2/genderapi_v2.py)

## Python projenizi sunucuda hazırlayın

Python 3.10 veya üzerini kullanın ve genderapi_v2.py dosyasını projenize indirin. Örnek, standart kütüphanedeki urllib.request ve json ile https://api.genderapi.io/api/v2/gender adresini Bearer API anahtarıyla çağırır; pip paketi gerekmez.

GENDERAPI_API_KEY değerini sunucu ortamında tanımlayın. YOUR_API_KEY çalışan bir anahtar değildir. Gerçek anahtarı sürüm kontrolüne, paylaşılan defterlere, React/Vue paketine veya tarayıcı koduna koymayın. Tarayıcı kendi kimlik doğrulaması olan sunucunuzu çağırmalı; GenderAPI isteğini sunucunuz göndermelidir. Dosyayı içe aktarmak veya açık demo seçeneği olmadan çalıştırmak istek göndermez.

**Python projenizi sunucuda hazırlayın**

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

- [Örnek dosyayı indir](https://www.genderapi.io/examples/v2/genderapi_v2.py)
- [Ücretsiz kullanım uç noktasıyla anahtarı doğrula](https://www.genderapi.io/tr/docs/v2/authentication#environment-setup)

## Yalnız veri kümesini kullanan ilk isteği gönderin

Aşağıdaki kodu indirdiğiniz dosyanın yanına single.py olarak kaydedip python3 single.py çalıştırın. predict, type: name, value: Alice ve options.ai_mode: off alanlarını JSON olarak gönderir. Tahmini data, istek ve ücret bilgisini meta içinde okuyun.

Tamamlanan bu sorgu, gender null olsa da 1 kredi kullanır. Örnek isim belirli bir sonuç garantisi vermez. İsim, e-posta veya kullanıcı adı gönderebilirsiniz; ülke bağlamını yalnız ilgili bilgiye sahipseniz ekleyin.

Yardımcı dosya açık AI modu ve 24 karakterlik onaltılık API anahtarı ister. Bu, anahtarın biçimini doğrular; sistemde bulunduğunu kanıtlamaz. Başarılı yanıtta meta.access.mode değerinin api_key olduğu kontrol edilir. IP denemesi yanıtı erişim uyuşmazlığı olarak reddedilir; bu kontrol yanıt sonrasında yapıldığı için tüketilmiş deneme kredisini geri alamaz.

**Yalnız veri kümesini kullanan ilk isteği gönderin**

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

- [Tekli istek parametreleri](https://www.genderapi.io/tr/docs/v2/request-parameters)

## Tahmini dayandığı bilgilerle birlikte değerlendirin

API’nin çıkardığı ilişki, kişinin kendi belirttiği cinsiyet değildir. Özgün girdiyi, yanıttaki kanıtları ve kişinin verdiği bilgileri ayrı saklayın. Tahmin bulunamaması geçerli bir sonuçtur; uygulamanızda bunu zorunlu bir cinsiyet kategorisine dönüştürmeyin.

| Alan | Nasıl kullanılmalı? |
| --- | --- |
| `data.gender / data.result_status` | male veya female değerini yalnızca identified sonucunda kullanın. unknown sonucunda gerçek JSON null değerini koruyun. |
| `data.name / data.match` | Dönen adı ve seçilen adayı inceleyin. Alt metin eşleşmesi, girdinin o ön ada sahip bir kişiye ait olduğunu kanıtlamaz. |
| `data.confidence / data.confidence_kind` | Güven skoru 0–1 aralığında veya null olur. observed_frequency kayıtlı sayımlardan, model_reported yapay zekânın bildirdiği skordan gelir. Eşikleri her tür için ayrı değerlendirin. |
| `data.source / data.sample_count` | dataset, ai ve none kaynaklarını ayırın. Yapay zekâ sonucunda kayıtlı örnek sayısı yoktur. Örnek sayısı, ölçülmüş doğruluk oranı değildir. |
| `meta.access.mode` | Hesap entegrasyonunda api_key değerini doğrulayın. Anahtar eksik veya tanınmıyorsa ortak IP denemesi kullanılabilir. |
| `meta.usage` | charged_credits ve billing_status alanlarını okuyun. Başarıyla tamamlanan unknown sonucu ücretlidir. Yanıtın ulaşmaması, işlemin ücretsiz olduğunu göstermez. |

- [Yanıt alanları ve tahmin bulunamayan sonuçlar](https://www.genderapi.io/tr/docs/v2/responses)
- [Doğruluk ve güven skoru](https://www.genderapi.io/tr/accuracy-methodology)
- [Veri kaynakları ve tarihli veri kümesi profili](https://www.genderapi.io/tr/data-provenance)

## Karma toplu sorgularda satır kimliğini koruyun

Karma toplu sorgular POST https://api.genderapi.io/api/v2/gender/batch adresine gönderilir. Hesap anahtarıyla en fazla 50, IP denemesinde 10 öğe kabul edilir. Bu örnekler hesap anahtarı gerektirir. Her öğeye kararlı ve benzersiz bir id, açık bir AI modu ve gerekiyorsa country ekleyin; isim, e-posta ve kullanıcı adlarını aynı grupta kullanabilirsiniz.

data içindeki her öğeyi ve meta.summary özetini inceleyin. HTTP 200 yanıtında öğe hataları bulunabilir; tüm öğeler başarısızsa sonuçları içeren üst düzey Problem yanıtı dönebilir. Başarıyla tamamlanan unknown sonuçlar succeeded sayılır. id ve index, sonucu doğru kaynak satıra bağlamanızı sağlar.

Daha büyük işleri en fazla 50 öğelik gruplara ayırıp başlangıçta sırayla gönderin. Sonraki gruba geçmeden yanıtı ve kullanım bilgisini kaydedin. Bağlantı, hesap veya teyit edilmemiş ücret sorunu varsa durup mevcut grubun durumunu netleştirin. Eşzamanlılığı hesap sınırlarını inceleyerek artırın; öğe sınırı bir hız garantisi değildir.

**Karma toplu sorgularda satır kimliğini koruyun**

```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)
```

- [Toplu sorgu alanları ve ücretlendirme](https://www.genderapi.io/tr/docs/v2/batch)

## Yapay zekânın ne zaman kullanılacağını seçin

forceToGenderize; isim, e-posta ve kullanıcı adı girdilerinde isteğe bağlıdır. Açıkken ai_mode alanını göndermeyin veya fallback kullanın. off ve always ile birlikte kullanılması 422 hatası verir. İsteğe başlamak için pozitif bakiye yeterlidir; son ücret bakiyeyi sıfırın altına düşürebilir.

Rumuz analizinde name: null iken cinsiyet tahmini dönebilir. Sonuç unknown da olabilir. Standart yedekleme veya rumuz analizi, doğru ya da dolu bir sonuç garantisi vermez.

Python yardımcısı ai_mode alanını her zaman ister. Takma ad için make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True) kullanın. force_to_genderize, JSON içinde forceToGenderize alanına çevrilir.

| İstek seçeneği | Davranış | Tamamlanan sorgunun maliyeti |
| --- | --- | --- |
| options.ai_mode: off | Yalnızca veri kümesini sorgular. | unknown dahil 1 kredi |
| options.ai_mode: fallback | Önce veri kümesini, cinsiyet tahmini bulunamazsa standart yapay zekâyı kullanır. Tekli sorguların varsayılanıdır. | Yapay zekâ yedeklemesi dahil toplam 1 kredi |
| options.ai_mode: always | Doğrudan yapay zekâya sorar. | 2 kredi |
| forceToGenderize: true | Önce veri kümesine bakar; tahmin bulunamazsa gerçek ön ad içermeyen kişisel rumuzların anlamını da yapay zekâyla yorumlayabilir. | Veri kümesinde tahmin bulunursa 1, yapay zekâ kullanılırsa toplam 2 kredi |

- [Yapay zekâ modları ve rumuz analizi](https://www.genderapi.io/tr/docs/v2/ai-options)
- [Krediler ve kullanım](https://www.genderapi.io/tr/docs/v2/credits-and-usage)

## Hatalardan sonra nasıl ilerleyeceğinize karar verin

Örnekler her işlemi bir kez gönderir; otomatik yeniden deneme yapmaz. Yeni gönderim yeni bir ücretli işlemdir. Zaman aşımı veya bağlantı hatası, istemcinin tam yanıt alamadığını gösterir; sunucunun durduğunu veya kredi kesilmediğini kanıtlamaz.

request_id ve ücret durumunu iş kaydınızla saklayın. Hata nesnesi kontrollü inceleme için yanıtı korur; özgün girdiyi içerebileceği için tüm nesneyi, yanıtı veya API anahtarını rutin günlüklere yazmayın.

| Durum | Uygulamanın kararı |
| --- | --- |
| Başarılı unknown | null, reason ve usage korunur. Tamamlanmış ücretli sonuçtur; otomatik tekrar edilecek hata değildir. |
| 422 | Problem Details alanlarında belirtilen girdiyi düzelttikten sonra yeni istek gönderin. |
| 401 / 403 | Hesap erişimini ve kredileri kontrol edin. Aynı isteği tekrarlamak temel sorunu çözmez. |
| 429 | Varsa Retry-After değerine uyun. Hata ve ücret durumunu doğrulayıp bilinçli bir sonraki deneme planlayın. |
| Ağ hatası, zaman aşımı veya okunamayan yanıt | Sonucun ve ücretin teyit edilmediğini kaydedin. Yeniden göndermeden önce durumu netleştirin; istemci tamamlanmış sunucu işlemini iptal edemez. |
| billing_status: unconfirmed | charged_credits ve remaining_credits null olabilir. request_id ile desteğe başvurun; null yerine sıfır yazmayın. |
| Bazı toplu öğeler başarısız | Tamamlanan öğeleri önce kaydedin. Hatalı öğelerin ücretini inceleyin; bütün grubu değil, yalnız uygun hataları yeniden gönderin. |

- [Hatalar ve yeniden deneme](https://www.genderapi.io/tr/docs/v2/errors-and-retries)
- [Krediler ve ücret teyidi](https://www.genderapi.io/tr/docs/v2/credits-and-usage)

## Zaman aşımı ve bağlantı davranışını bilin

urllib için 10 saniyelik zaman aşımı, engelleyici soket işlemlerine uygulanır; isteğin tamamı için kesin bir toplam süre sınırı değildir. Örnek yönlendirmeleri kapatır, başarılı JSON yanıtlarını ayrıştırır, HTTP Problem yanıtlarını korur ve otomatik tekrar yapmaz.

Yerel testler başarı, unknown, kısmi toplu hata, erişim modu ve bağlantı hatalarını yapay yanıtlarla sınar. Canlı tahmin veya kredi işlemi yapmaz; erişilebilirlik, doğruluk veya üretim gecikmesi ölçümü değildir. Aşağıdaki her açık demo komutu ayrı ücretli sorgu gönderir.

**Zaman aşımı ve bağlantı davranışını bilin**

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

- [Python HTTP başvuru belgesi](https://docs.python.org/3/library/urllib.request.html)
- [Python HTTP başvuru belgesi](https://docs.python.org/3/library/urllib.error.html)

## Python neden null yerine None gösteriyor?

Python JSON çözücüsü null değerini None olarak dönüştürür. Bu bilinmeyen değeri koruyun; varsayılan cinsiyete veya sıfır güven puanına çevirmeyin.

## Bu örnek resmî bir SDK paketi mi?

Bu rehber indirilebilir bir HTTP yardımcı dosyası kullanır; ayrı yayımlanmış bir pip veya npm SDK paketi değildir. Dosyayı uygulamanızın yanında tutun ve kullanımınıza göre inceleyip uyarlayın.

## gender null dönerse kredi kesilir mi?

Evet. Başarıyla tamamlanan unknown sonucu da ücretlidir. Bu rehberdeki ai_mode: off örneği 1 kredi kullanır. Sonucu ve meta.usage alanını saklayın; bilinmeyen sonucu otomatik tekrar etmeyin.

## Eski V1 istemci kodunu doğrudan kullanabilir miyim?

Bu örnekler V2 type/value istek alanlarını ve data/meta yanıtını kullanır. V1 paketi veya bağlayıcısı aynı sözleşmeyi kullanmak zorunda değildir. Uç noktayı, kimlik doğrulamayı, alanları ve ücret kurallarını doğrulamadan yalnız URL’yi değiştirmeyin.

## Başvuru belgeleri

- [V2 kimlik doğrulama](https://www.genderapi.io/tr/docs/v2/authentication)
- [V2 yanıtları](https://www.genderapi.io/tr/docs/v2/responses)
- [Toplu sorgu sınırları](https://www.genderapi.io/tr/docs/v2/batch)
- [Kredi kullanımı](https://www.genderapi.io/tr/docs/v2/credits-and-usage)