Integra GenderAPI.io V2 con JavaScript y Node.js

Ejecuta la integración en tu servidor Node.js

Utiliza Node.js 22 o posterior y descarga genderapi-v2.mjs. El módulo ES llama a https://api.genderapi.io/api/v2/gender con una clave Bearer mediante fetch y AbortSignal.timeout integrados; no necesita un paquete npm. La extensión .mjs permite importarlo desde otro módulo ES sin modificar package.json.

Define GENDERAPI_API_KEY en el entorno del servidor. YOUR_API_KEY no es una clave válida. No incluyas la clave real en el control de versiones, cuadernos compartidos, paquetes React/Vue ni código del navegador. El navegador debe llamar a tu servidor autenticado y este debe enviar la petición a GenderAPI.io. Importar el archivo o ejecutarlo sin la opción explícita de demo no envía consultas.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Descargar el archivo de ejemplo →
• Verifica tu clave con el endpoint de uso sin coste →

Envía tu primera consulta solo al conjunto de datos

Guarda el código como single.mjs junto al módulo descargado y ejecuta node single.mjs. Envía type: name, value: Alice y options.ai_mode: off. Lee la predicción en response.data y la información de solicitud y facturación en response.meta.

Esta consulta completada cuesta 1 crédito, aunque gender sea null. El nombre de ejemplo no garantiza un resultado. Puedes enviar nombres, correos o usuarios; añade country solo si tienes contexto relevante.

El archivo auxiliar exige un modo de IA explícito y una clave hexadecimal de 24 caracteres. Esto valida el formato, no su existencia. En respuestas correctas verifica que meta.access.mode sea api_key. Rechaza ip_trial como discrepancia de acceso, pero esa comprobación posterior a la respuesta no recupera créditos de prueba ya consumidos.

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

• Parámetros de consultas individuales →

Interpreta el resultado junto con sus evidencias

Una asociación inferida no equivale al género declarado por la persona. Conserva por separado el dato original, las evidencias de la respuesta y la información facilitada por la persona. unknown es un resultado válido; no lo conviertas en una categoría inventada.

• Campos de respuesta y resultados desconocidos →
• Exactitud y confianza →
• Fuentes de datos y perfil del conjunto de datos →

Conserva la identidad de cada fila en los lotes mixtos

Envía lotes mixtos mediante POST https://api.genderapi.io/api/v2/gender/batch. Se admiten hasta 50 elementos con clave de cuenta o 10 en la prueba por IP. Estos ejemplos requieren una clave de cuenta. Asigna a cada elemento un id estable y único, un modo de IA explícito y country cuando corresponda. Puedes combinar nombres, correos y usuarios.

Revisa cada elemento de data y el resumen meta.summary. HTTP 200 puede incluir errores de elementos; si todos fallan, puede devolverse un Problem de nivel superior con los resultados. Los resultados unknown completados cuentan como succeeded. id e index permiten vincular cada resultado con su fila original.

Divide los trabajos grandes en grupos de hasta 50 y empieza enviándolos secuencialmente. Guarda la respuesta y el uso antes del siguiente grupo. Si hay problemas de conexión, acceso o facturación sin confirmar, detente y aclara el estado del grupo actual. Ajusta la concurrencia según los límites de la cuenta; el límite de elementos no garantiza una velocidad.

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

• Campos y facturación de lotes →

Elige cuándo utilizar la IA

forceToGenderize es opcional para nombres, correos electrónicos y nombres de usuario. Si lo activas, omite ai_mode o utiliza fallback; combinarlo con off o always devuelve un error 422. Basta con un saldo inicial positivo para iniciar la consulta, aunque el cargo final deje el saldo por debajo de cero.

El análisis de alias puede devolver un género con name: null. También puede devolver unknown. Ni el respaldo estándar de IA ni el análisis de alias garantizan una respuesta correcta o distinta de null.

El auxiliar JavaScript exige options.ai_mode. Para alias, envía forceToGenderize: true y options: { ai_mode: 'fallback' }.

• Opciones de IA y análisis de alias →
• Créditos y uso →

Decide cómo continuar después de un error

Los ejemplos envían cada operación una sola vez y no reintentan automáticamente. Cada nuevo envío es una nueva operación facturable. Un error de red o tiempo de espera indica que el cliente no recibió una respuesta completa; no demuestra que el servidor se haya detenido ni que no se hayan consumido créditos.

Guarda request_id y el estado de facturación junto con el registro del trabajo. El objeto de error conserva la respuesta para una revisión controlada; puede contener la entrada original. No escribas el objeto completo, la respuesta ni la clave API en registros rutinarios.

• Errores y reintentos →
• Créditos y confirmación del cargo →

Comprende los tiempos de espera y el comportamiento de conexión

El límite predeterminado es de 10.000 milisegundos mediante AbortSignal.timeout e incluye leer el cuerpo de la respuesta. Detener el cliente no demuestra que el servidor haya detenido el procesamiento o la facturación. El módulo bloquea redirecciones, distingue errores HTTP de respuestas ilegibles y no reintenta automáticamente.

Las pruebas locales usan respuestas simuladas para éxito, unknown, errores parciales, acceso y conexión. No realizan predicciones reales ni consumen créditos; tampoco miden disponibilidad, exactitud o latencia de producción. Cada comando explícito de demo mostrado envía una consulta facturable independiente.

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

• Referencia HTTP de Node.js →
• Referencia HTTP de Node.js →

Preguntas frecuentes