# JavaScript ve Node.js ile GenderAPI V2 entegrasyonu

> Node.js fetch ile tekli ve karma toplu V2 sorguları gönderin. Bearer kimlik doğrulamayı, data/meta alanlarını ve hata durumlarını örneklerle uygulayın.

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

Last reviewed: 2026-09-27

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

Node.js 22+. İ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.mjs)

## Entegrasyonu Node.js sunucunuzda çalıştırın

Node.js 22 veya üzerini kullanın ve genderapi-v2.mjs dosyasını projenize indirin. ES modülü yerleşik fetch ve AbortSignal.timeout ile https://api.genderapi.io/api/v2/gender adresini Bearer API anahtarıyla çağırır; npm paketi gerekmez. .mjs uzantısı başka bir ES modülünden package.json değiştirmeden içe aktarmayı sağlar.

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.

**Entegrasyonu Node.js sunucunuzda çalıştırın**

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

- [Örnek dosyayı indir](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [Ü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 modülün yanına single.mjs olarak kaydedip node single.mjs çalıştırın. type: name, value: Alice ve options.ai_mode: off gönderilir. Tahmini response.data, istek ve ücret bilgisini response.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**

```javascript
import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}
```

- [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**

```javascript
import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}
```

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

JavaScript yardımcısı options.ai_mode alanını her zaman ister. Takma ad için forceToGenderize: true ile options: { ai_mode: 'fallback' } gönderin.

| İ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

Varsayılan süre sınırı AbortSignal.timeout ile 10.000 milisaniyedir ve yanıt gövdesinin okunmasını kapsar. İstemciyi durdurmak sunucunun işlemi veya ücretlendirmeyi durdurduğunu kanıtlamaz. Modül yönlendirmeleri kapatır, HTTP hatalarını okunamayan yanıtlardan ayırır 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
node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch
```

- [Node.js HTTP başvuru belgesi](https://nodejs.org/api/globals.html#fetch)
- [Node.js HTTP başvuru belgesi](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay)

## Bu kodu tarayıcıda çalıştırabilir miyim?

API anahtarını korumak için kodu sunucuda çalıştırın. Tarayıcı paketi anahtarı kullanıcıya açar. Tarayıcı kendi kimlik doğrulaması olan arka ucunuzu çağırmalı; GenderAPI isteğini arka uç göndermelidir.

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