İsim, e-posta ve kullanıcı adlarını toplu sorgulama
POST /gender/batch, API anahtarıyla 1–50, IP denemesinde en fazla 10 öğelik items dizisi kabul eder. Yalnızca isim, e-posta veya kullanıcı adı gönderebilir ya da üçünü birleştirebilirsiniz. Her öğenin country, forceToGenderize ve options alanları ayrıdır. Kimlikler isteğe bağlıdır ve benzersiz olmalıdır.
Sonuçlar girdi sırasını korur; index, varsa id, charged_credits ve data veya error alanlarından yalnızca birini içerir. HTTP 200, öğe düzeyinde hata içerebilir; her öğeyi kontrol edin. meta.summary içinde total, succeeded, identified, unknown ve failed bulunur. Belirsiz tahmin başarılı ve ücretli bir öğedir.
İstek doğrulama veya planlama hatası, kredi düşülmeden toplu isteği reddeder. Çalıştırılan tüm öğeler başarısızsa API, data dizisi ve eski results takma alanıyla 2xx dışı Problem yanıtı döndürür. İadesi doğrulanan başarısız öğe sıfır kredidir. Ücretlendirme doğrulanmadıysa öğe tutarlarını kesin kabul etmeyin.
Programlama dilinizi seçin. API anahtarınızı ayarlayın, ardından örneği sunucunuzda çalıştırın.
Yeniden denemeler dahil her tahmin isteği yeni ve ücretlendirilebilir bir işlemdir. Örnekler otomatik yeniden deneme yapmaz. Yeni istekten önce ücretlendirme durumunu kontrol edin.
Çalıştırmadan önce: erişim ve hata yönetimi
Örnekleri sunucunuzda çalıştırın. İşlem ortamındaki GENDERAPI_API_KEY değişkenini mevcut anahtarınıza ayarlayın. Tanınmayan anahtar IP denemesine yönlenebildiğinden meta.access.mode değerinin api_key olduğunu doğrulayın.
HTTP 4xx ve 5xx JSON yanıtlarında hata gövdesi korunur ve program sıfırdan farklı çıkış koduyla sonlanır. Yeniden denemeden önce code, action ve meta.usage.billing_status alanlarını kontrol edin. HTTP 200 toplu yanıtlarda her öğenin data veya error alanını da inceleyin.
Hata ve yeniden deneme rehberi →POSIX kabuğunda cURL 7.76+. Terminalinizde çalıştırın. Çalıştırma ortamı dokümantasyonu
Node.js 22+; yerleşik fetch. example.mjs olarak kaydedin ve node example.mjs çalıştırın. Çalıştırma ortamı dokümantasyonu
Python 3.10+; standart kütüphane. example.py olarak kaydedin ve python3 example.py çalıştırın. Çalıştırma ortamı dokümantasyonu
cURL uzantılı PHP 8+. example.php olarak kaydedin ve php example.php çalıştırın. Çalıştırma ortamı dokümantasyonu
Java 17+; standart HTTP istemcisi. GenderApiExample.java olarak kaydedin ve java GenderApiExample.java çalıştırın. Çalıştırma ortamı dokümantasyonu
.NET 8+ konsol uygulaması. Konsol projesinde Program.cs olarak kullanın, ardından dotnet run çalıştırın. Çalıştırma ortamı dokümantasyonu
Go 1.22+; standart kütüphane. main.go olarak kaydedin ve go run main.go çalıştırın. Çalıştırma ortamı dokümantasyonu
Toplu yanıtı yorumlama
Bu bağımsız temsili örnek veri kümesi eşleşmesi, belirsiz sonuç ve sağlayıcı hatası içerir. Yukarıdaki isteğin beklenen çıktısı değil, kısmi başarılı HTTP 200 örneğidir. İki başarılı öğenin her biri 1 kredi, başarısız öğe ise doğrulanmış şekilde sıfır kredidir.
{
"data": [
{
"index": 0,
"id": "known",
"charged_credits": 1,
"data": {
"input": {
"type": "name",
"value": "Onur",
"country": "TR"
},
"name": "onur",
"gender": "male",
"country": "TR",
"confidence": 0.9,
"confidence_kind": "observed_frequency",
"sample_count": 100,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "onur",
"method": "normalized",
"scope": "country",
"country": "TR"
}
}
},
{
"index": 1,
"id": "missing",
"charged_credits": 1,
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
}
},
{
"index": 2,
"id": "failed",
"charged_credits": 0,
"error": {
"type": "urn:genderapi:problem:ai_upstream_error",
"title": "ai upstream error",
"status": 502,
"detail": "The AI provider could not complete the request.",
"instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
"code": "ai_upstream_error",
"request_id": "11111111-1111-4111-8111-111111111111",
"documentation": "https://api.genderapi.io/api/v2/errors",
"action": "inspect_billing_before_retry"
}
}
],
"meta": {
"request_id": "11111111-1111-4111-8111-111111111111",
"duration_ms": 12,
"access": {
"mode": "ip_trial",
"reason": "api_key_missing"
},
"usage": {
"charged_credits": 2,
"remaining_credits": 6,
"billing_status": "confirmed",
"resets_at": "2026-09-26T12:00:00.000Z",
"limit": 10,
"period_seconds": 86400
},
"summary": {
"total": 3,
"succeeded": 2,
"identified": 1,
"unknown": 1,
"failed": 1
}
}
}Toplu sorgu kredilerini ve yeniden denemeleri planlama
Mevcut API anahtarınızı Bearer başlığında, Content-Type: application/json ile gönderin. Her toplu istek yeni işlemdir. Kısmi hatada ücretlendirmeyi kontrol edip yalnızca başarısız öğeleri yeniden gönderin; başarılı öğeler tekrar gönderilirse yeniden ücretlendirilir.
Toplu öğelerde varsayılan AI off’tur; başarılı öğe 1 kredidir. Açıkça seçilen fallback, yapay zekâ dahil toplam 1; always 2 kredidir. forceToGenderize, çözülen veri kümesi sonucunda 1, yapay zekâda toplam 2 kredidir. Başarılı belirsiz sonuçlar ücretlidir. Başlamak için 1 pozitif kredi yeterlidir; nihai tutar bakiyeyi eksiye düşürebilir.