GenderAPI.io V2: الأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين في طلب مجمّع

الأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين في طلب مجمّع

المعامل	النوع	مطلوب	القيمة الافتراضية	الوصف
`items`	`array<object>`	نعم	`—`	1–50 عنصر تقدير؛ و10 عناصر كحد أقصى في التجربة حسب عنوان IP. تحافظ النتائج على ترتيب الإدخال.
`items[].type`	`string`	نعم	`—`	فئة الإدخال: name أو email أو username.
`items[].value`	`string`	نعم	`—`	مطلوب. 1–254 حرفًا؛ غير فارغ ودون أحرف تحكم. يجب أن تكون قيم email بصيغة بريد إلكتروني صالحة.
`items[].country`	`string`	لا	`—`	رمز ISO 3166-1 alpha-2 اختياري بأحرف كبيرة، مثل TR أو US. قد يرجع البحث الخاص بدولة إلى مجموعة البيانات العامة.
`items[].forceToGenderize`	`boolean`	لا	`false`	ابحث في مجموعة البيانات أولًا، ثم استخدم الذكاء الاصطناعي الذي يفسّر الأسماء المستعارة إذا لم توجد نتيجة. مدعوم لـ name وemail وusername.
`items[].options`	`object`	لا	`—`	كائن يضم خيارات الذكاء الاصطناعي لكل مُدخل.
`items[].options.ai_mode`	`string`	لا	`off`	القيم المسموح بها: off وfallback وalways. مع forceToGenderize: true، احذف هذا الحقل أو استخدم fallback.
`items[].id`	`string`	لا	`—`	معرّف اختياري من 1–64 حرفًا في JSON لطلبات POST. يُعاد بجوار نتيجة العنصر في الطلب المجمّع، ويجب أن يكون فريدًا داخل الطلب المجمّع. يُقبل في التقديرات الفردية لكنه لا يُعاد في الاستجابة. غير مدعوم في استعلامات GET.

يقبل GenderAPI.io V2 الأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين معًا عبر POST https://api.genderapi.io/api/v2/gender/batch. أرسل مصفوفة items تضم 1–50 عنصرًا عند الوصول بمفتاح API، أو 10 عناصر كحد أقصى في التجربة حسب عنوان IP. يستخدم كل عنصر type وvalue، ويمكن أن تكون له قيم خاصة به في country وforceToGenderize وoptions. المعرّفات اختيارية ويجب أن تكون فريدة داخل الطلب المجمّع.

تحافظ النتائج على ترتيب الإدخال، وتتضمن index والمعرّف الاختياري id وcharged_credits وواحدًا فقط من data أو error. قد تحتوي استجابة HTTP 200 على أخطاء في عناصر منفردة، لذا افحص كل عنصر. يعرض meta.summary القيم total وsucceeded وidentified وunknown وfailed. التقدير غير المعروف عنصر ناجح تُخصم أرصدته.

إذا فشل التحقق من الطلب أو تخطيطه، يُرفض الطلب المجمّع قبل الخصم. وإذا فشلت كل العناصر المنفَّذة، تعيد API استجابة Problem برمز حالة غير 2xx، مع مصفوفة data والاسم البديل القديم results. لا تكلّف العناصر الفاشلة شيئًا بعد تأكيد الاسترداد. وإذا لم يُؤكَّد الخصم، فلا تعدّ تكاليف العناصر نهائية.

اختر لغة البرمجة. إعداد مفتاح API، ثم شغّل المثال على خادمك.

كل طلب تقدير عملية جديدة مدفوعة، حتى عند إعادة المحاولة. لا تعيد هذه الأمثلة المحاولة تلقائيًا. تحقّق من حالة الخصم قبل إرسال طلب آخر.

قبل التشغيل: الوصول ومعالجة الأخطاء

شغّل هذه الأمثلة على خادمك. اضبط GENDERAPI_API_KEY في بيئة العملية على مفتاح API الحالي. تأكد من أن قيمة meta.access.mode هي api_key: فالمفتاح غير المعروف قد يؤدي إلى استخدام التجربة حسب عنوان IP.

في استجابات JSON ذات رموز HTTP 4xx و5xx، يُحتفظ بجسم الخطأ وينتهي المثال برمز خروج غير صفري. تحقّق من code وaction وmeta.usage.billing_status قبل إعادة المحاولة. وفي استجابات الطلب المجمّع ذات HTTP 200، افحص أيضًا data أو error في كل عنصر.

دليل الأخطاء وإعادة المحاولة ←

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Ahmed",
      "country": "SA"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ في واجهة أوامر POSIX. شغّله في الطرفية. وثائق بيئة التشغيل

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Ahmed",
      "country": "SA"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+ مع fetch المدمج. احفظه باسم example.mjs وشغّل node example.mjs. وثائق بيئة التشغيل

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Ahmed\",\"country\":\"SA\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender/batch",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+ مع المكتبة القياسية. احفظه باسم example.py وشغّل python3 example.py. وثائق بيئة التشغيل

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"contact-1","type":"name","value":"Ahmed","country":"SA"},{"id":"contact-2","type":"email","value":"alice.smith@example.com","options":{"ai_mode":"fallback"}},{"id":"contact-3","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+ مع امتداد cURL. احفظه باسم example.php وشغّل php example.php. وثائق بيئة التشغيل

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Ahmed\",\"country\":\"SA\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender/batch"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+ مع عميل HTTP القياسي. احفظه باسم GenderApiExample.java وشغّل java GenderApiExample.java. وثائق بيئة التشغيل

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Ahmed\",\"country\":\"SA\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

تطبيق وحدة تحكم (console) على .NET 8+. استخدمه كملف Program.cs في مشروع console، ثم شغّل dotnet run. وثائق بيئة التشغيل

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Ahmed\",\"country\":\"SA\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+ مع المكتبة القياسية. احفظه باسم main.go وشغّل go run main.go. وثائق بيئة التشغيل

قراءة استجابة طلب مجمّع

يجمع هذا المثال بين نتيجتين حقيقيتين جرى الحصول عليهما في 1 أكتوبر 2026، هما تطابق في مجموعة البيانات ونتيجة غير معروفة، وبين فشل توضيحي لدى مزوّد الخدمة. وهو يوضّح استجابة HTTP 200 بنجاح جزئي، لا المخرجات المتوقعة للطلب المجمّع السابق. تكلفة كل عنصر من العنصرين الناجحين رصيد واحد؛ أما العنصر الفاشل فخصمه المؤكد صفر.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Ahmed",
          "country": "SA"
        },
        "name": "ahmed",
        "gender": "male",
        "country": "SA",
        "confidence": 0.9936783299029697,
        "confidence_kind": "observed_frequency",
        "sample_count": 6802,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "ahmed",
          "method": "normalized",
          "scope": "country",
          "country": "SA"
        }
      }
    },
    {
      "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
    }
  }
}

حقول نتائج الطلب المجمّع

الحقل	النوع	يمكن أن يكون null	مثال	الوصف
`data`	`array<object>`	لا	`[…]`	نتائج مرتّبة. يحتوي كل عنصر على تقدير أو خطأ؛ فافحص كل العناصر.
`data[].index`	`integer`	لا	`0`	الموضع في مصفوفة items المُرسلة، بدءًا من الصفر.
`data[].id`	`string`	لا	`"contact-1"`	معرّف الإدخال الخاص بك، ولا يظهر إلا إذا أرسلته.
`data[].charged_credits`	`integer`	لا	`1`	صافي خصم العنصر بعد الاسترداد المؤكد. لا تعدّه نهائيًا إذا لم يُؤكَّد الخصم الإجمالي.
`data[].data`	`object`	لا	`{…}`	موجود للعنصر الناجح، بما في ذلك النتائج غير المعروفة. يستخدم حقول التقدير الموضحة في دليل الاستجابات.
`data[].error`	`object`	لا	`{…}`	موجود بدلًا من data للعنصر الفاشل. يستخدم حقول Problem Details الموضحة في دليل الأخطاء.

حقول ملخص الطلب المجمّع

الحقل	النوع	يمكن أن يكون null	مثال	الوصف
`meta.summary.total`	`integer`	لا	`3`	إجمالي عدد العناصر في الطلب المجمّع.
`meta.summary.succeeded`	`integer`	لا	`2`	العناصر الناجحة، بما في ذلك التقديرات غير المعروفة.
`meta.summary.identified`	`integer`	لا	`1`	العناصر الناجحة التي لها جنس غير null.
`meta.summary.unknown`	`integer`	لا	`1`	العناصر الناجحة التي يكون فيها gender هو null؛ وتُخصم أرصدة هذه النتائج.
`meta.summary.failed`	`integer`	لا	`1`	العناصر الفاشلة. total = succeeded + failed؛ succeeded = identified + unknown.

البيانات الوصفية للوصول والخصم والطلب

الحقل	النوع	يمكن أن يكون null	مثال	الوصف
`meta.request_id`	`string`	لا	`"550e8400-e29b-41d4-a716-446655440000"`	معرّف فريد لمحاولة HTTP هذه؛ ويُرسل أيضًا في X-Request-ID.
`meta.duration_ms`	`integer`	لا	`42`	مدة معالجة الطلب بالمللي ثانية.
`meta.access.mode`	`string`	لا	`"api_key"`	api_key أو ip_trial أو unauthenticated. عند استخدام حساب مدفوع، تحقّق من ظهور api_key.
`meta.access.reason`	`string`	نعم	`null`	سبب الانتقال إلى التجربة حسب عنوان IP: api_key_missing أو api_key_invalid أو api_key_not_found؛ وإلا null.
`meta.usage.charged_credits`	`integer`	نعم	`1`	صافي الأرصدة المخصومة. صفر قبل الخصم أو بعد استرداد كامل مؤكد؛ وnull إذا لم يُؤكَّد الخصم.
`meta.usage.remaining_credits`	`integer`	نعم	`99`	الرصيد عند اكتمال العملية. قد يكون سالبًا؛ وnull إذا لم يتوفر أو لم يُؤكَّد الخصم.
`meta.usage.billing_status`	`string`	لا	`"confirmed"`	not_charged أو confirmed أو unconfirmed. تحقّق منه قبل إعادة محاولة تقدير فاشل.
`meta.usage.resets_at`	`string`	نعم	`"2026-09-27T12:00:00.000Z"`	موعد تجديد التجربة حسب عنوان IP بتوقيت UTC (ISO 8601)؛ وnull لحسابات مفاتيح API أو إذا كان غير معروف.
`meta.usage.limit`	`integer`	نعم	`10`	حصة التجربة حسب عنوان IP؛ وnull لحسابات مفاتيح API.
`meta.usage.period_seconds`	`integer`	نعم	`86400`	مدة فترة التجربة حسب عنوان IP بالثواني؛ وnull لحسابات مفاتيح API.

تخطيط الأرصدة وإعادة المحاولة في الطلبات المجمّعة

صادِق باستخدام مفتاح API الحالي في ترويسة Bearer، وأرسل Content-Type: application/json. كل طلب مجمّع تُرسله عملية جديدة. إذا أعدت المحاولة بعد فشل جزئي، فأرسل العناصر الفاشلة فقط بعد التحقق من الخصم؛ إذ تُخصم أرصدة العناصر الناجحة مرة أخرى إذا أُعيد إرسالها.

في عناصر الطلب المجمّع، يكون الذكاء الاصطناعي على off افتراضيًا، وتكلفة كل عنصر ناجح رصيد واحد. وتكلفة fallback الصريح أيضًا رصيد واحد إجمالًا، بما في ذلك الذكاء الاصطناعي. تكلفة always رصيدان. وتكلفة forceToGenderize رصيد واحد للنتيجة الموجودة في مجموعة البيانات أو رصيدان إذا استُخدم الذكاء الاصطناعي. تُخصم أرصدة النتائج غير المعروفة الناجحة. يكفي رصيد ابتدائي موجب قدره 1 لبدء الطلب المجمّع؛ وقد يترك الخصم النهائي رصيدًا سالبًا.

معالجة قائمة جهات اتصال دون فقدان أي صف

تتعامل نقطة نهاية الطلبات المجمّعة مع قوائم الأسماء فقط، وقوائم عناوين البريد الإلكتروني فقط، والمُدخلات المختلطة. باستخدام مفتاح API، قسّم العمل إلى طلبات مجمّعة لا يتجاوز كل منها 50 عنصرًا؛ وتسمح التجربة حسب عنوان IP بعشرة عناصر كحد أقصى في كل طلب. تتبّع موضعك في العمل، وامنح كل عنصر id فريدًا داخل الطلب المجمّع. يبدأ index المُعاد من الصفر داخل الطلب المجمّع المُرسل، لا داخل قائمة جهات الاتصال كاملة.

الخطوة	ما يجب حفظه أو التحقق منه	لماذا يهم ذلك
1. جهّز كل طلب مجمّع	احتفظ بالصف المصدر وبمعرّف العنصر؛ واضبط country وخيارات الذكاء الاصطناعي لكل عنصر.	لا تفترض أن الاسم فريد بين جميع جهات الاتصال.
2. اقرأ الاستجابة كاملة	احفظ meta.request_id وطابق كل عنصر في data[] عبر id أو index.	قد تحتوي استجابة HTTP 200 على تقديرات ناجحة وعلى أخطاء في عناصر منفردة معًا.
3. احفظ النتائج الناجحة	احتفظ بالتقديرات المحدَّدة وغير المعروفة، بما في ذلك قيم JSON null وحقول الأدلة.	النتيجة غير المعروفة مكتملة وتُخصم أرصدتها؛ وليست صفًا فاشلًا يُعاد إرساله تلقائيًا.
4. طابِق الأخطاء والأرصدة	افحص كل error وmeta.usage.billing_status قبل أن تقرر إرسال طلب جديد.	بعد تأكيد الخصم، أعد محاولة العناصر الفاشلة التي يبرر خطؤها ذلك فقط. أما العناصر الناجحة فستُخصم أرصدتها مرة أخرى.
5. أجّل إعادة المحاولة غير المؤكدة	احفظ معرّف الطلب إذا لم يُؤكَّد الخصم أو إذا جعل خطأ في الشبكة نتيجة العملية غير معروفة.	لا تُعِد إرسال الطلب المجمّع كله دون تحقق؛ اتبع أولًا إرشادات الأخطاء والخصم.

اختيار وضع التقدير لكل جهة اتصال

يستخدم هذا الطلب القابل للتشغيل ثلاث قواعد مختلفة: مجموعة البيانات فقط لاسم كامل، والرجوع العادي إلى الذكاء الاصطناعي لعنوان بريد إلكتروني، والرجوع إلى الذكاء الاصطناعي مع تفسير الأسماء المستعارة لاسم مستخدم. هذه مُدخلات توضيحية، ولا تعني أن جهات الاتصال الثلاث ستحصل كلها على جنس. اختر لغة البرمجة فوق الكود، واضبط GENDERAPI_API_KEY قبل تشغيل المثال.

من دون forceToGenderize، يكون الذكاء الاصطناعي في عناصر الطلب المجمّع على off افتراضيًا، بخلاف عمليات البحث الفردية. حدّد fallback صراحةً إذا أردت استخدام الرجوع العادي إلى الذكاء الاصطناعي. تكلفة off والرجوع العادي كليهما رصيد واحد لكل عنصر ناجح؛ ويتخطى always مجموعة البيانات وتكلفته رصيدان. وتكلفة forceToGenderize رصيد واحد للنتيجة الموجودة في مجموعة البيانات أو رصيدان إجمالًا إذا استُخدم الذكاء الاصطناعي. تُخصم أرصدة النتائج غير المعروفة الناجحة أيضًا. لا تجمع forceToGenderize مع off أو always.