# Χρήση του GenderAPI.io V2 με JavaScript και Node.js

> Καλέστε το GenderAPI.io V2 από το Node.js με το ενσωματωμένο fetch. Κατεβάστε ένα ES module για μεμονωμένα αιτήματα και μικτές παρτίδες, για την ανάγνωση των αποκρίσεων data/meta και για τον χειρισμό σφαλμάτων που αφορούν πιστώσεις.

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

Last reviewed: 2026-09-29

## Περιβάλλον εκτέλεσης και παράδειγμα για λήψη

Node.js 22+. Παράδειγμα ενσωμάτωσης HTTP για λήψη. Δεν υπάρχει SDK δημοσιευμένο χωριστά.

- [Λήψη του παραδείγματος](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)

## Διατήρηση της ενσωμάτωσης σε διακομιστή Node.js

Αυτός ο οδηγός καλεί το endpoint του GenderAPI.io V2 https://api.genderapi.io/api/v2/gender με το κλειδί API στην κεφαλίδα Bearer. Χρησιμοποιήστε Node.js 22 ή νεότερη έκδοση και κατεβάστε το genderapi-v2.mjs στο έργο σας. Το ES module χρησιμοποιεί τα ενσωματωμένα fetch και AbortSignal.timeout και δεν απαιτεί κανένα πακέτο npm. Χάρη στην επέκταση .mjs μπορείτε να το εισαγάγετε από άλλο ES module χωρίς να αλλάξετε το package.json.

Ορίστε το GENDERAPI_API_KEY στο περιβάλλον του διακομιστή. Μην το τοποθετείτε στον κώδικα JavaScript του React, του Vue ή σε άλλο κώδικα που εκτελείται στο πρόγραμμα περιήγησης. Αφήστε τον διακομιστή σας να ελέγχει την ταυτότητα των χρηστών της εφαρμογής και να καλεί το GenderAPI.io. Το YOUR_API_KEY στο παρακάτω παράδειγμα δεν είναι έγκυρο κλειδί. Η εισαγωγή του module ή η εκτέλεσή του χωρίς ρητή επιλογή εκτέλεσης δεν στέλνει κανένα αίτημα.

**Ρύθμιση του περιβάλλοντος Node.js**

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

- [Λήψη του genderapi-v2.mjs](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [Έλεγχος του κλειδιού με το δωρεάν endpoint χρήσης](https://www.genderapi.io/el/docs/v2/authentication#environment-setup)

## Αποστολή αιτήματος POST με JSON και ρητή πολιτική AI

Αποθηκεύστε τον κώδικα ως single.mjs δίπλα στο module που κατεβάσατε και εκτελέστε node single.mjs. Στέλνει τα πεδία V2 type και value μαζί με options.ai_mode: off. Η πρόβλεψη βρίσκεται στο response.data, ενώ οι πληροφορίες για το αίτημα και τη χρέωση βρίσκονται στο response.meta.

Μια ολοκληρωμένη αναζήτηση κοστίζει 1 πίστωση, ακόμη κι όταν το gender είναι null. Το όνομα του παραδείγματος δεν εγγυάται συγκεκριμένο αποτέλεσμα.

Το βοηθητικό module απαιτεί ρητή λειτουργία AI και ένα δεκαεξαδικό κλειδί 24 χαρακτήρων και έπειτα ελέγχει ότι το meta.access.mode έχει την τιμή api_key. Μια επιτυχής απόκριση της δοκιμαστικής πρόσβασης προκαλεί σφάλμα μη αναμενόμενου τρόπου πρόσβασης αντί να συνεχίσει σιωπηρά. Ο διακομιστής μπορεί να έχει ήδη καταναλώσει μια δοκιμαστική πίστωση πριν εντοπίσει το module τη διαφορά.

**Μεμονωμένη αναζήτηση σε Node.js**

```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;
}
```

- [Όλα τα πεδία των μεμονωμένων αιτημάτων](https://www.genderapi.io/el/docs/v2/request-parameters)

## Αποθήκευση του αποτελέσματος μαζί με τα τεκμήρια

Μια συσχέτιση που συνάγεται δεν είναι το φύλο που δηλώνει ένα άτομο. Αποθηκεύστε χωριστά την αρχική είσοδο, τα τεκμήρια που επιστράφηκαν και ό,τι έχει δηλώσει το ίδιο το άτομο. Ένα άγνωστο αποτέλεσμα είναι έγκυρο αποτέλεσμα και δεν πρέπει να γίνει μια μαντεμένη κατηγορία στην εφαρμογή σας.

| Πεδίο | Χρήση |
| --- | --- |
| `data.gender / data.result_status` | Χρησιμοποιήστε male ή female μόνο μαζί με identified. Σε άγνωστο αποτέλεσμα διατηρήστε την εγγενή τιμή JSON null. |
| `data.name / data.match` | Ελέγξτε το όνομα που επιστράφηκε και τον υποψήφιο που επιλέχθηκε. Μια αντιστοίχιση σε υποσυμβολοσειρά δεν αποδεικνύει ότι η είσοδος ανήκει σε άτομο με αυτό το όνομα. |
| `data.confidence / data.confidence_kind` | Ο βαθμός βεβαιότητας εκφράζεται σε κλίμακα από 0 έως 1 ή είναι null. Το observed_frequency βασίζεται σε αποθηκευμένες συχνότητες, ενώ το model_reported είναι τιμή που αναφέρει το AI. Αξιολογήστε τα όρια χωριστά για κάθε τύπο. |
| `data.source / data.sample_count` | Διακρίνετε τα dataset, ai και none. Τα αποτελέσματα του AI δεν έχουν αποθηκευμένο μέγεθος δείγματος. Ένα μέγεθος δείγματος δεν είναι μετρημένη ακρίβεια. |
| `meta.access.mode` | Σε μια ενσωμάτωση με λογαριασμό ελέγξτε ότι επιστρέφεται api_key. Τα κλειδιά που λείπουν ή δεν αναγνωρίζονται μπορεί αντί γι' αυτό να χρησιμοποιήσουν την κοινόχρηστη δοκιμαστική πρόσβαση IP. |
| `meta.usage` | Διαβάστε τα charged_credits και billing_status. Ένα επιτυχές άγνωστο αποτέλεσμα χρεώνεται. Μια απόκριση που χάθηκε δεν αποδεικνύει ότι το αίτημα ήταν δωρεάν. |

- [Πεδία απόκρισης και άγνωστα αποτελέσματα](https://www.genderapi.io/el/docs/v2/responses)
- [Ακρίβεια και βαθμός βεβαιότητας](https://www.genderapi.io/el/accuracy-methodology)
- [Πηγές δεδομένων και χρονολογημένο προφίλ της βάσης δεδομένων](https://www.genderapi.io/el/data-provenance)

## Επεξεργασία μιας μικτής παρτίδας με διατήρηση του id κάθε γραμμής

Το GenderAPI.io V2 επεξεργάζεται μικτές παρτίδες μέσω POST https://api.genderapi.io/api/v2/gender/batch: έως 50 στοιχεία με κλειδί λογαριασμού ή έως 10 με τη δοκιμαστική πρόσβαση IP. Αυτά τα παραδείγματα απαιτούν κλειδί λογαριασμού. Δώστε σε κάθε στοιχείο ένα σταθερό και μοναδικό id και μια ρητή λειτουργία AI. Μια παρτίδα μπορεί να συνδυάζει ονόματα, διευθύνσεις email και ονόματα χρήστη, και κάθε στοιχείο μπορεί να έχει προαιρετικό πλαίσιο country.

Διαβάστε κάθε στοιχείο στο data και τη σύνοψη στο meta.summary. Μια απόκριση HTTP 200 μπορεί να περιέχει σφάλματα μεμονωμένων στοιχείων. Μια παρτίδα στην οποία απέτυχαν όλα τα στοιχεία μπορεί να επιστρέψει μια απόκριση Problem ανώτατου επιπέδου με τα αποτελέσματα. Τα επιτυχή άγνωστα αποτελέσματα μετρώνται στο succeeded. Με τα index και id συνδέετε κάθε αποτέλεσμα με τη σωστή αρχική γραμμή.

Για μεγαλύτερες εργασίες χωρίστε την είσοδο σε ομάδες των 50 στοιχείων το πολύ και στείλτε τις αρχικά μία κάθε φορά. Αποθηκεύστε κάθε απόκριση και τη σχετική χρήση πριν προχωρήσετε στην επόμενη ομάδα. Σταματήστε σε περίπτωση σφάλματος μεταφοράς, σφάλματος πρόσβασης στον λογαριασμό ή μη επιβεβαιωμένης χρέωσης και διευκρινίστε την κατάσταση της τρέχουσας ομάδας. Εισαγάγετε παράλληλες αποστολές μόνο αφού ελέγξετε τα όρια του λογαριασμού σας. Το μέγιστο μέγεθος παρτίδας δεν εγγυάται συγκεκριμένη ικανότητα επεξεργασίας.

**Αναζήτηση σε παρτίδα σε Node.js**

```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;
}
```

- [Είσοδος, αποτελέσματα και χρέωση των παρτίδων](https://www.genderapi.io/el/docs/v2/batch)

## Πότε να χρησιμοποιείται AI

Το forceToGenderize είναι προαιρετικό για ονόματα, διευθύνσεις email και ονόματα χρήστη. Όταν είναι ενεργό, παραλείψτε το ai_mode ή χρησιμοποιήστε fallback. Τα off και always δεν συνδυάζονται με αυτή την επιλογή και επιστρέφουν 422. Ένα θετικό αρχικό υπόλοιπο αρκεί για να ξεκινήσει ένα αίτημα, ακόμη κι αν η τελική χρέωση κάνει το υπόλοιπο αρνητικό.

Η λειτουργία ψευδωνύμων μπορεί να επιστρέψει φύλο μαζί με name: null. Μπορεί επίσης να δώσει άγνωστο αποτέλεσμα. Ούτε η κανονική εφεδρική χρήση AI ούτε η ανάλυση ψευδωνύμων εγγυώνται σωστή απάντηση ή τιμή διαφορετική από null.

Το βοηθητικό module για JavaScript απαιτεί πάντα options.ai_mode. Για την ανάλυση ψευδωνύμων στείλτε forceToGenderize: true μαζί με options: { ai_mode: 'fallback' }.

| Επιλογή αιτήματος | Συμπεριφορά | Πιστώσεις για επιτυχή αναζήτηση |
| --- | --- | --- |
| options.ai_mode: off | Χρησιμοποιεί μόνο το σύνολο δεδομένων. | 1, και για άγνωστο αποτέλεσμα |
| options.ai_mode: fallback | Ελέγχει πρώτα το σύνολο δεδομένων και έπειτα χρησιμοποιεί κανονικό AI, αν δεν επιστραφεί φύλο. Είναι η προεπιλογή για τα μεμονωμένα αιτήματα. | 1 συνολικά, μαζί με την εφεδρική χρήση AI |
| options.ai_mode: always | Χρησιμοποιεί απευθείας AI. | 2 |
| forceToGenderize: true | Ελέγχει πρώτα το σύνολο δεδομένων και έπειτα αφήνει το AI να ερμηνεύσει ένα προσωπικό ψευδώνυμο ή ένα alias, ακόμη και χωρίς πραγματικό μικρό όνομα. | 1 για αποτέλεσμα από το σύνολο δεδομένων, 2 συνολικά αν χρησιμοποιηθεί AI |

- [Επιλογές AI και ανάλυση ψευδωνύμων](https://www.genderapi.io/el/docs/v2/ai-options)
- [Πιστώσεις και χρήση](https://www.genderapi.io/el/docs/v2/credits-and-usage)

## Απόφαση για το τι θα κάνετε μετά από σφάλμα

Τα παραδείγματα στέλνουν κάθε λειτουργία μόνο μία φορά. Δεν την επαναλαμβάνουν ποτέ αυτόματα: μια νέα αποστολή είναι νέα λειτουργία που χρεώνεται. Μια λήξη χρονικού ορίου ή ένα σφάλμα σύνδεσης σημαίνει ότι ο client δεν έλαβε πλήρη απόκριση. Δεν αποδεικνύει ότι ο διακομιστής διέκοψε την επεξεργασία ούτε ότι δεν χρεώθηκαν πιστώσεις.

Αποθηκεύστε το request_id που επιστράφηκε και την κατάσταση της χρέωσης μαζί με την εγγραφή της εργασίας σας. Το σφάλμα που δημιουργεί το παράδειγμα διατηρεί την απόκριση για ελεγχόμενη ανάλυση, αλλά μπορεί να περιέχει την αρχική είσοδο: μη γράφετε στα συνήθη αρχεία καταγραφής ούτε ολόκληρο το σφάλμα ούτε την απόκριση ούτε το κλειδί API.

| Κατάσταση | Απόφαση της εφαρμογής |
| --- | --- |
| Επιτυχές άγνωστο αποτέλεσμα | Διατηρήστε τα null, reason και usage. Είναι ολοκληρωμένο αποτέλεσμα που χρεώθηκε και όχι αποτυχημένη γραμμή για αυτόματη επανάληψη. |
| Σφάλμα επικύρωσης 422 | Διορθώστε την είσοδο που αναφέρεται στα πεδία του Problem Details πριν στείλετε νέο αίτημα. |
| 401 / 403 | Ελέγξτε την πρόσβαση στον λογαριασμό ή το διαθέσιμο υπόλοιπο. Η εκ νέου αποστολή του ίδιου αιτήματος δεν λύνει την αιτία. |
| 429 | Τηρήστε την κεφαλίδα Retry-After, αν υπάρχει. Ελέγξτε το σφάλμα και την κατάσταση της χρέωσης και έπειτα προγραμματίστε συνειδητά την επόμενη προσπάθεια. |
| Σφάλμα δικτύου, λήξη χρονικού ορίου ή μη αναγνώσιμη απόκριση | Καταγράψτε ότι το αποτέλεσμα και η χρέωση δεν έχουν επιβεβαιωθεί. Διευκρινίστε την κατάσταση πριν στείλετε ξανά. Ο client δεν μπορεί να ακυρώσει μια επεξεργασία που έχει ήδη ολοκληρωθεί στον διακομιστή. |
| billing_status: unconfirmed | Τα charged_credits και remaining_credits μπορεί να είναι null. Επικοινωνήστε με την υποστήριξη αναφέροντας το request_id πριν από νέα προσπάθεια. Μην αντικαθιστάτε το null με μηδέν πιστώσεις. |
| Σφάλματα σε ορισμένα στοιχεία μιας παρτίδας | Αποθηκεύστε πρώτα τα στοιχεία που ολοκληρώθηκαν. Ελέγξτε τα στοιχεία που απέτυχαν και τη σχετική χρέωση. Στείλτε ξανά μόνο τα επιλέξιμα σφάλματα και όχι ολόκληρη την παρτίδα. |

- [Problem Details και αποφάσεις για νέες προσπάθειες](https://www.genderapi.io/el/docs/v2/errors-and-retries)
- [Πιστώσεις και επιβεβαίωση της χρέωσης](https://www.genderapi.io/el/docs/v2/credits-and-usage)

## Το χρονικό όριο του fetch και οι έλεγχοι της απόκρισης

Το προεπιλεγμένο χρονικό όριο είναι 10.000 χιλιοστά του δευτερολέπτου μέσω AbortSignal.timeout, μαζί με την ανάγνωση του σώματος της απόκρισης. Μια διακοπή από την πλευρά του client δεν αποδεικνύει ότι σταμάτησε η επεξεργασία ή η χρέωση στον διακομιστή. Το module απενεργοποιεί τις ανακατευθύνσεις, διακρίνει τα σφάλματα HTTP από τις μη αναγνώσιμες αποκρίσεις και δεν επαναλαμβάνει ποτέ αυτόματα τα αιτήματα.

Οι έλεγχοι με προσομοιωμένη μεταφορά καλύπτουν επιτυχείς αποκρίσεις, άγνωστα αποτελέσματα, μερικώς επιτυχείς παρτίδες, εφεδρική χρήση διαπιστευτηρίων και σφάλματα. Δεν ζητούν πραγματικές προβλέψεις ούτε λειτουργίες με πιστώσεις και δεν μετρούν τη διαθεσιμότητα ή την ακρίβεια στην παραγωγή. Κάθε ρητή εντολή επίδειξης παρακάτω στέλνει δικό της αίτημα που χρεώνεται.

**Προαιρετικές ρητές επιδείξεις σε Node.js**

```bash
node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch
```

- [Τεκμηρίωση του Node.js για το fetch](https://nodejs.org/api/globals.html#fetch)
- [Τεκμηρίωση του Node.js για το AbortSignal.timeout](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay)

## Μπορώ να χρησιμοποιήσω αυτόν τον κώδικα σε JavaScript που εκτελείται στο πρόγραμμα περιήγησης;

Κρατήστε τον στον διακομιστή σας. Ο κώδικας εφαρμογής που εκτελείται στο πρόγραμμα περιήγησης εκθέτει το κλειδί API στους χρήστες. Από το πρόγραμμα περιήγησης καλέστε το δικό σας backend με έλεγχο ταυτότητας και αφήστε το να στείλει το αίτημα στο GenderAPI.io.

## Καταναλώνει πιστώσεις ένα άγνωστο αποτέλεσμα;

Ναι. Μια κανονική επιτυχής αναζήτηση κοστίζει 1 πίστωση, ακόμη κι όταν το gender είναι null. Η κανονική εφεδρική χρήση AI περιλαμβάνεται σε αυτή την πίστωση. Η λειτουργία always κοστίζει 2 πιστώσεις. Το forceToGenderize κοστίζει 1 πίστωση αν το αποτέλεσμα προέρχεται από το σύνολο δεδομένων ή 2 αν χρησιμοποιηθεί AI.

## Επαναλαμβάνει το παράδειγμα ένα αίτημα που απέτυχε;

Όχι. Κάθε νέο αίτημα είναι ξεχωριστή λειτουργία. Ελέγξτε το σφάλμα, τα αποτελέσματα των μεμονωμένων στοιχείων και την κατάσταση της χρέωσης πριν αποφασίσετε αν θα στείλετε ξανά. Μια απόκριση που λείπει δεν αποδεικνύει ότι η προηγούμενη προσπάθεια ήταν δωρεάν.

## Πρέπει να εγκαταστήσω κάποιο πακέτο;

Όχι. Κατεβάστε το παράδειγμα απευθείας από αυτόν τον οδηγό του GenderAPI.io. Δεν έχει εξαρτήσεις εκτέλεσης από εξωτερικά πακέτα και δεν είναι ξεχωριστό SDK δημοσιευμένο στο pip ή στο npm. Ελέγξτε το και προσαρμόστε το στην εφαρμογή σας. Για τη σύμβαση του API ισχύει η τεκμηρίωση του GenderAPI.io V2.

## Τεκμηρίωση αναφοράς

- [Έλεγχος ταυτότητας στο GenderAPI.io V2](https://www.genderapi.io/el/docs/v2/authentication)
- [Πεδία απόκρισης του V2](https://www.genderapi.io/el/docs/v2/responses)
- [Αποτελέσματα και όρια των παρτίδων](https://www.genderapi.io/el/docs/v2/batch)
- [Τεκμηρίωση για σφάλματα και νέες προσπάθειες](https://www.genderapi.io/el/docs/v2/errors-and-retries)