Integra GenderAPI.io V2 con Python

Prepara tu proyecto Python en el servidor

Utiliza Python 3.10 o posterior y descarga genderapi_v2.py en tu proyecto. El ejemplo llama a https://api.genderapi.io/api/v2/gender con una clave Bearer mediante urllib.request y json de la biblioteca estándar; no necesita un paquete pip.

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.

python3 --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.py junto al archivo descargado y ejecuta python3 single.py. predict envía type: name, value: Alice y options.ai_mode: off en JSON. Lee la predicción en data y los datos de solicitud y facturación en 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.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

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

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• 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 Python exige ai_mode. Para alias, utiliza make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). force_to_genderize se convierte en forceToGenderize en JSON.

• 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 tiempo de espera de 10 segundos de urllib se aplica a operaciones de socket bloqueantes; no es un límite estricto para la duración total. El ejemplo bloquea redirecciones, analiza respuestas JSON correctas, conserva los Problem HTTP 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.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Referencia HTTP de Python →
• Referencia HTTP de Python →

Preguntas frecuentes