# Usar a GenderAPI.io V2 com Python

> Chame a GenderAPI.io V2 a partir do Python com um exemplo baseado na biblioteca padrão. Envie nomes, endereços de e-mail e nomes de usuário, processe lotes mistos e leia os campos data/meta.

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

Last reviewed: 2026-09-29

## Runtime e exemplo para download

Python 3.10+. Exemplo de integração HTTP para download; não é um SDK publicado separadamente.

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

## Preparar um projeto Python no lado do servidor

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 Python 3.10 ou mais recente e baixe genderapi_v2.py para o seu projeto. O exemplo usa urllib.request e json da biblioteca padrão do Python; nenhum pacote pip é necessário.

Defina GENDERAPI_API_KEY no ambiente do servidor. YOUR_API_KEY no exemplo a seguir não é uma chave válida. Não coloque credenciais reais em arquivos sob controle de versão, notebooks compartilhados ou aplicações no lado do cliente. Importar o módulo ou executá-lo sem opções de demonstração não envia nenhuma requisição.

**Configurar o ambiente Python**

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

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

## Enviar uma requisição explícita que usa apenas o conjunto de dados

Salve o código a seguir como single.py ao lado do arquivo baixado e execute python3 single.py. O módulo auxiliar envia type: name, value: Alice e options.ai_mode: off como JSON. A previsão fica em data, enquanto as informações da requisição e da cobrança ficam em meta.

Uma chamada bem-sucedida custa 1 crédito, mesmo com um resultado desconhecido, e o nome de exemplo não garante uma previsão. make_item aceita name, email ou username e exige um modo de IA explícito. Acrescente country somente se você tiver um contexto relevante.

Antes de enviar qualquer coisa, o módulo auxiliar exige uma chave de API hexadecimal de 24 caracteres. Ele verifica o formato da chave, e não se a chave existe. O módulo também rejeita respostas bem-sucedidas do teste por IP como um modo de acesso inesperado. Essa verificação acontece depois que a resposta é recebida e não pode devolver um crédito do teste por IP que já foi usado.

**Consulta individual em Python**

```python
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"])
```

- [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 Python**

```python
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)
```

- [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 Python sempre exige ai_mode. Use make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True) para a interpretação de apelidos. O módulo converte force_to_genderize no campo JSON forceToGenderize.

| 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 comportamento de rede do exemplo

O tempo limite de 10 segundos do urllib vale para operações de socket bloqueantes e não é um limite garantido para a duração total da requisição. O exemplo desativa os redirecionamentos HTTP, processa respostas JSON bem-sucedidas e preserva as respostas HTTP Problem. Ele nunca faz novas tentativas automaticamente.

Os testes locais usam respostas de transporte simuladas para chamadas bem-sucedidas, resultados desconhecidos, lotes parcialmente bem-sucedidos, acesso à conta e erros. Eles verificam a lógica do exemplo, mas não medem a disponibilidade da API em produção, a precisão da previsão nem os tempos de resposta. Cada comando de demonstração explícito abaixo envia a própria requisição, que é cobrada.

**Demonstrações explícitas opcionais em Python**

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

- [Documentação do Python sobre urllib.request](https://docs.python.org/3/library/urllib.request.html)
- [Documentação do Python sobre HTTPError](https://docs.python.org/3/library/urllib.error.html)

## Por que o Python mostra None em vez de null?

O decodificador JSON do Python converte null em None. Preserve o valor desconhecido e não o substitua por um gênero padrão ou por um valor de confiança zero ao salvar ou exportar o resultado.

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