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

> Chame a GenderAPI.io V2 a partir do Node.js com o fetch nativo. Baixe um módulo ES para requisições individuais e lotes mistos, para ler respostas data/meta e para tratar erros que afetam os créditos.

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

Last reviewed: 2026-09-29

## Runtime e exemplo para download

Node.js 22+. Exemplo de integração HTTP para download; não é um SDK publicado separadamente.

- [Baixar o exemplo](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)

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

**Configurar o ambiente Node.js**

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

- [Baixar genderapi-v2.mjs](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [Verificar a chave com o endpoint gratuito de uso](https://www.genderapi.io/pt/docs/v2/authentication#environment-setup)

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

**Consulta individual em 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;
}
```

- [Todos os campos das requisições individuais](https://www.genderapi.io/pt/docs/v2/request-parameters)

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

| Campo | Uso |
| --- | --- |
| `data.gender / data.result_status` | Use male ou female somente com identified. Em um resultado desconhecido, preserve o valor null nativo do JSON. |
| `data.name / data.match` | Verifique o nome retornado e o candidato selecionado. Uma correspondência com uma substring não comprova que a entrada pertence a uma pessoa com esse nome. |
| `data.confidence / data.confidence_kind` | A confiança está em uma escala de 0 a 1 ou é null. observed_frequency se baseia em frequências armazenadas; model_reported é um valor fornecido pela IA. Avalie os limites separadamente para cada tipo. |
| `data.source / data.sample_count` | Diferencie dataset, ai e none. Resultados da IA não têm um tamanho de amostra armazenado. Um tamanho de amostra não é um valor de precisão medido. |
| `meta.access.mode` | Em uma integração com conta, verifique se o valor informado é api_key. Chaves ausentes ou não reconhecidas podem usar o teste por IP compartilhado. |
| `meta.usage` | Leia charged_credits e billing_status. Um resultado desconhecido bem-sucedido é cobrado. Uma resposta perdida não comprova que a requisição foi gratuita. |

- [Campos da resposta e resultados desconhecidos](https://www.genderapi.io/pt/docs/v2/responses)
- [Precisão e confiança explicadas](https://www.genderapi.io/pt/accuracy-methodology)
- [Fontes de dados e perfil datado do banco de dados](https://www.genderapi.io/pt/data-provenance)

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

**Consulta em lote em 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;
}
```

- [Entrada, resultados e cobrança dos lotes](https://www.genderapi.io/pt/docs/v2/batch)

## 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ção da requisição | Comportamento | Créditos por consulta bem-sucedida |
| --- | --- | --- |
| options.ai_mode: off | Usa apenas o conjunto de dados. | 1, inclusive para um resultado desconhecido |
| options.ai_mode: fallback | Consulta primeiro o conjunto de dados e depois usa a IA comum se nenhum gênero for retornado. É o padrão das requisições individuais. | 1 no total, incluindo o fallback de IA |
| options.ai_mode: always | Usa a IA diretamente. | 2 |
| forceToGenderize: true | Consulta primeiro o conjunto de dados e depois deixa a IA interpretar um apelido pessoal ou um alias, mesmo sem um nome próprio real. | 1 para um resultado encontrado no conjunto de dados; 2 no total se a IA for usada |

- [Opções de IA e interpretação de apelidos](https://www.genderapi.io/pt/docs/v2/ai-options)
- [Créditos e uso](https://www.genderapi.io/pt/docs/v2/credits-and-usage)

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

| Situação | Decisão na aplicação |
| --- | --- |
| Resultado desconhecido bem-sucedido | Preserve null, reason e usage. É um resultado concluído e cobrado, e não uma linha com falha que deva ser tentada novamente de forma automática. |
| Erro de validação 422 | Corrija a entrada indicada nos campos de Problem Details antes de enviar uma nova requisição. |
| 401 / 403 | Verifique o acesso à conta ou o saldo disponível. Reenviar a mesma requisição não resolve a causa. |
| 429 | Respeite o cabeçalho Retry-After, se houver. Verifique o erro e o status da cobrança e depois planeje a próxima tentativa de forma consciente. |
| Erro de rede, tempo limite esgotado ou resposta ilegível | Registre que o resultado e a cobrança não foram confirmados. Investigue a situação antes de reenviar. O cliente não pode desfazer um processamento que o servidor já concluiu. |
| billing_status: unconfirmed | charged_credits e remaining_credits podem ser null. Entre em contato com o suporte antes de uma nova tentativa e informe o request_id. Não substitua null por zero créditos. |
| Erros em alguns itens de um lote | Salve primeiro os itens concluídos. Verifique os itens com falha e a cobrança correspondente e reenvie apenas os erros adequados para isso, e não o lote inteiro. |

- [Problem Details e decisões sobre novas tentativas](https://www.genderapi.io/pt/docs/v2/errors-and-retries)
- [Créditos e confirmação da cobrança](https://www.genderapi.io/pt/docs/v2/credits-and-usage)

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

**Demonstrações explícitas opcionais em Node.js**

```bash
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](https://nodejs.org/api/globals.html#fetch)
- [Documentação do Node.js sobre AbortSignal.timeout](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay)

## Posso usar este código em JavaScript executado no navegador?

Mantenha o código no seu servidor. Código de aplicação executado no navegador deixa a chave de API visível para os usuários. Chame o seu próprio backend autenticado a partir do navegador e deixe que ele envie a requisição à GenderAPI.io.

## Um resultado desconhecido consome créditos?

Sim. Uma consulta comum bem-sucedida custa 1 crédito, mesmo quando gender é null. O fallback de IA automático comum está incluído nesse crédito. O modo always custa 2 créditos, e forceToGenderize custa 1 crédito se o resultado vier do conjunto de dados ou 2 se a IA for usada.

## O exemplo repete uma requisição que falhou?

Não. Cada nova requisição é uma operação separada. Verifique o erro, os resultados de cada item e o status da cobrança antes de decidir reenviar. Uma resposta ausente não prova que a tentativa anterior foi gratuita.

## Preciso instalar um pacote?

Não. Baixe o exemplo diretamente deste guia da GenderAPI.io. Ele não tem dependências de execução de pacotes externos e não é um SDK separado publicado via pip ou npm. Revise-o e adapte-o à sua aplicação. Para o contrato da API, vale a documentação da GenderAPI.io V2.

## Documentação de referência

- [Autenticação na GenderAPI.io V2](https://www.genderapi.io/pt/docs/v2/authentication)
- [Campos da resposta na V2](https://www.genderapi.io/pt/docs/v2/responses)
- [Resultados e limites dos lotes](https://www.genderapi.io/pt/docs/v2/batch)
- [Documentação sobre erros e novas tentativas](https://www.genderapi.io/pt/docs/v2/errors-and-retries)