Usar a GenderAPI.io V2 com JavaScript e Node.js

Manter a integração em um servidor Node.js

Este guia chama o endpoint da GenderAPI.io V2 https://api.genderapi.io/api/v2/gender com a chave de API no cabeçalho Bearer. Use Node.js 22 ou mais recente e baixe genderapi-v2.mjs para o seu projeto. O módulo ES usa o fetch nativo e AbortSignal.timeout; nenhum pacote npm é necessário. Graças à extensão .mjs, você pode importar o módulo de outro módulo ES sem alterar o package.json.

Defina GENDERAPI_API_KEY no ambiente do servidor. Não coloque a chave em código JavaScript de React, Vue ou qualquer outro código executado no navegador. Deixe o seu servidor autenticar os usuários da aplicação e chamar a GenderAPI.io. YOUR_API_KEY no exemplo a seguir não é uma chave válida, e importar o módulo ou executá-lo sem uma opção de execução explícita não envia nenhuma requisição.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Baixar genderapi-v2.mjs →
• Verificar a chave com o endpoint gratuito de uso →

Enviar uma requisição POST com JSON e uma política de IA explícita

Salve o código como single.mjs ao lado do módulo baixado e execute node single.mjs. A requisição envia os campos type e value da V2 junto com options.ai_mode: off. A previsão fica em response.data, enquanto as informações da requisição e da cobrança ficam em response.meta.

Uma consulta concluída custa 1 crédito, mesmo quando gender é null, e o nome de exemplo não garante um resultado específico.

O módulo auxiliar exige um modo de IA explícito e uma chave hexadecimal de 24 caracteres e depois verifica se meta.access.mode tem o valor api_key. Uma resposta bem-sucedida do teste por IP gera um erro de modo de acesso inesperado em vez de continuar silenciosamente. O servidor pode já ter usado um crédito do teste por IP antes que o módulo detecte a diferença.

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

• Todos os campos das requisições individuais →

Salvar o resultado junto com as evidências

Uma associação inferida não é o gênero declarado por uma pessoa. Salve separadamente a entrada original, as evidências retornadas e o que a pessoa declarou. Um resultado desconhecido é um resultado válido e não deve se transformar em uma categoria adivinhada na sua aplicação.

• Campos da resposta e resultados desconhecidos →
• Precisão e confiança explicadas →
• Fontes de dados e perfil datado do banco de dados →

Processar um lote misto e preservar o id de cada linha

A GenderAPI.io V2 processa lotes mistos via POST https://api.genderapi.io/api/v2/gender/batch: até 50 itens com uma chave de conta ou 10 com o teste por IP. Estes exemplos exigem uma chave de conta. Dê a cada item um id estável e único e um modo de IA explícito. Um lote pode combinar nomes, endereços de e-mail e nomes de usuário, e cada item pode ter um contexto country opcional.

Leia cada item em data e o resumo em meta.summary. Uma resposta HTTP 200 pode conter erros em itens individuais, e um lote em que todos os itens falharam pode retornar uma resposta Problem de nível superior com os resultados. Resultados desconhecidos bem-sucedidos são contados em succeeded. Com index e id, você associa cada resultado à linha original correta.

Divida tarefas maiores em grupos de no máximo 50 itens e, no início, envie-os um de cada vez. Salve cada resposta e o uso correspondente antes de passar para o próximo grupo. Pare em caso de erro de transporte, erro de acesso à conta ou cobrança não confirmada e descubra primeiro o que aconteceu com o grupo atual. Só envie em paralelo depois de verificar os limites da sua conta. O tamanho máximo do lote não garante uma capacidade de processamento específica.

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

• Entrada, resultados e cobrança dos lotes →

Decidir quando usar a IA

forceToGenderize é opcional para nomes, endereços de e-mail e nomes de usuário. Quando ativado, omita ai_mode ou use fallback; off e always não podem ser combinados com essa opção e retornam 422. Um saldo inicial positivo basta para iniciar uma requisição, mesmo que a cobrança final deixe o saldo negativo.

O modo de apelidos pode retornar um gênero junto com name: null. Ele também pode dar um resultado desconhecido. Nem o fallback de IA comum nem a interpretação de apelidos garantem uma resposta correta ou um valor diferente de null.

O módulo auxiliar para JavaScript sempre exige options.ai_mode. Envie forceToGenderize: true junto com options: { ai_mode: 'fallback' } para a interpretação de apelidos.

• Opções de IA e interpretação de apelidos →
• Créditos e uso →

Decidir o que fazer depois de um erro

Os exemplos enviam cada operação uma única vez. Eles nunca fazem uma nova tentativa automaticamente: reenviar é uma nova operação, que pode ser cobrada. Um tempo limite esgotado ou um erro de conexão significa que o cliente não recebeu uma resposta completa. Isso não prova que o servidor interrompeu o processamento nem que nenhum crédito foi cobrado.

Salve o request_id retornado e o status da cobrança junto com o registro da sua tarefa. O objeto de erro preserva a resposta para uma análise controlada, mas pode conter a entrada original: não grave o objeto inteiro, a resposta e a chave de API em arquivos de log comuns.

• Problem Details e decisões sobre novas tentativas →
• Créditos e confirmação da cobrança →

Conhecer o tempo limite do fetch e as verificações da resposta

O tempo limite padrão é de 10.000 milissegundos via AbortSignal.timeout, incluindo a leitura do corpo da resposta. Uma interrupção no lado do cliente não prova que o processamento ou a cobrança no servidor foram interrompidos. O módulo desativa os redirecionamentos, diferencia erros HTTP de respostas ilegíveis e nunca faz novas tentativas automaticamente.

Os testes com transporte simulado cobrem respostas bem-sucedidas, resultados desconhecidos, lotes parcialmente bem-sucedidos, fallback de credenciais e erros. Eles não buscam previsões reais nem executam operações com créditos, e não medem a disponibilidade ou a precisão em produção. Cada comando de demonstração explícito abaixo envia a própria requisição, que é cobrada.

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

• Documentação do Node.js sobre fetch →
• Documentação do Node.js sobre AbortSignal.timeout →

Perguntas frequentes