JavaScript ve Node.js ile GenderAPI V2 entegrasyonu

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.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Örnek dosyayı indir →
• Ücretsiz kullanım uç noktasıyla anahtarı doğrula →

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.

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 →

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.

• Yanıt alanları ve tahmin bulunamayan sonuçlar →
• Doğruluk ve güven skoru →
• Veri kaynakları ve tarihli veri kümesi profili →

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.

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 →

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.

• Yapay zekâ modları ve rumuz analizi →
• Krediler ve kullanım →

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.

• Hatalar ve yeniden deneme →
• Krediler ve ücret teyidi →

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.

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 →
• Node.js HTTP başvuru belgesi →

Sık sorulan sorular