Entenda a resposta JSON
Respostas individuais bem-sucedidas contêm data e meta. O exemplo do conjunto de dados a seguir é uma resposta real obtida em 1º de outubro de 2026 com uma chave de API; apenas o saldo da conta foi substituído. Ele não representa uma precisão medida do produto, e uma requisição real pode retornar um resultado diferente. Requisições com chave de API informam access.mode: api_key e retornam null nos campos de cota exclusivos do teste; requisições pelo teste por IP informam ip_trial com o limite do teste e o horário de redefinição.
{
"data": {
"input": {
"type": "name",
"value": "João",
"country": "BR"
},
"name": "joão",
"gender": "male",
"country": "BR",
"confidence": 0.995472640699399,
"confidence_kind": "observed_frequency",
"sample_count": 25622,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "joão",
"method": "normalized",
"scope": "country",
"country": "BR"
}
},
"meta": {
"request_id": "ddd9cbc6-6728-4ecb-b6ec-4d4c706daf83",
"duration_ms": 21,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Campos da resposta de previsão
| Campo | Tipo | Pode ser null | Exemplo | Descrição |
|---|---|---|---|---|
data.input | object | Não | {"type":"name","value":"João","country":"BR"} | Tipo de entrada, valor e país. forceToGenderize é incluído quando for true. |
data.name | string | Sim | "joão" | Nome próprio correspondente ou extraído; null quando não houver nenhum. |
data.gender | string | Sim | "male" | male, female ou JSON null. É uma inferência, não uma identidade pessoal verificada. |
data.result_status | string | Não | "identified" | identified quando um gênero é retornado; caso contrário, unknown. |
data.reason | string | Sim | null | null para resultados identified. Motivos de resultado desconhecido: not_found, no_name_candidate, ambiguous ou insufficient_evidence. |
data.confidence | number | Sim | 0.95 | Valor de 0 a 1 ou null. Um gênero null tem confiança null. |
data.confidence_kind | string | Sim | "observed_frequency" | observed_frequency: contagem dominante no conjunto de dados / total. model_reported: valor da IA, não uma probabilidade calibrada. null quando indisponível. |
data.sample_count | integer | Sim | 1200 | Tamanho da amostra no conjunto de dados ou null. A IA não inventa uma contagem de amostras. |
data.source | string | Não | "dataset" | dataset, ai ou none. |
data.country | string | Sim | "BR" | Associação de país vinda do conjunto de dados (dataset) ou ai_association, ou null. Não indica nacionalidade, residência nem etnia. |
data.country_source | string | Sim | "dataset" | Origem da associação ao país: dataset, ai_association ou null. |
data.match | object | Não | {"name":"joão","method":"normalized","scope":"country","country":"BR"} | Nome correspondente no conjunto de dados, método (normalized, token, substring ou model_inference), escopo country/global e país da correspondência. Evidências indisponíveis são null. |
Campos de entrada retornados
| Campo | Tipo | Pode ser null | Exemplo | Descrição |
|---|---|---|---|---|
data.input.type | string | Não | "name" | Categoria de entrada: name, email ou username. |
data.input.value | string | Não | "João" | Valor enviado para a previsão. |
data.input.country | string | Sim | "BR" | Contexto de país enviado; null quando omitido. |
data.input.forceToGenderize | boolean | Não | true | Presente apenas quando o modo de apelidos está ativado; caso contrário, omitido. |
Campos de correspondência no conjunto de dados
| Campo | Tipo | Pode ser null | Exemplo | Descrição |
|---|---|---|---|---|
data.match.name | string | Sim | "joão" | Candidato selecionado no conjunto de dados; null quando nenhuma linha foi selecionada. |
data.match.method | string | Sim | "normalized" | normalized, token, substring ou model_inference; null quando indisponível. |
data.match.scope | string | Sim | "country" | country ou global nas consultas ao conjunto de dados; null para IA ou ausência de evidências. |
data.match.country | string | Sim | "BR" | País da linha selecionada no conjunto de dados; null para linhas globais ou IA. |
Metadados de acesso, cobrança e requisição
| Campo | Tipo | Pode ser null | Exemplo | Descrição |
|---|---|---|---|---|
meta.request_id | string | Não | "550e8400-e29b-41d4-a716-446655440000" | Identificador único desta tentativa HTTP; também enviado em X-Request-ID. |
meta.duration_ms | integer | Não | 42 | Tempo de processamento da requisição em milissegundos. |
meta.access.mode | string | Não | "api_key" | api_key, ip_trial ou unauthenticated. Verifique api_key ao usar uma conta paga. |
meta.access.reason | string | Sim | null | Motivo do uso do teste por IP: api_key_missing, api_key_invalid ou api_key_not_found; caso contrário, null. |
meta.usage.charged_credits | integer | Sim | 1 | Créditos líquidos cobrados. Zero antes da cobrança ou após reembolso integral confirmado; null se a cobrança não estiver confirmada. |
meta.usage.remaining_credits | integer | Sim | 99 | Saldo ao concluir a operação. Pode ser negativo; null se indisponível ou se a cobrança não estiver confirmada. |
meta.usage.billing_status | string | Não | "confirmed" | not_charged, confirmed ou unconfirmed. Verifique antes de repetir uma previsão com falha. |
meta.usage.resets_at | string | Sim | "2026-09-27T12:00:00.000Z" | Momento da renovação do teste por IP em UTC (ISO 8601); null para contas com chave de API ou quando desconhecido. |
meta.usage.limit | integer | Sim | 10 | Cota do teste por IP; null para contas com chave de API. |
meta.usage.period_seconds | integer | Sim | 86400 | Janela do teste por IP em segundos; null para contas com chave de API. |
Um resultado desconhecido bem-sucedido
HTTP 200 significa que a operação foi concluída; não garante um gênero. Preserve o JSON null em vez de convertê-lo em male, female, uma string vazia ou confiança zero. Verifique data.result_status e data.reason separadamente dos erros HTTP.
Este exemplo real só com conjunto de dados, obtido em 1º de outubro de 2026, retorna source: none e reason: not_found e ainda custa 1 crédito. Uma linha empatada no conjunto de dados pode retornar reason: ambiguous mantendo seu sample_count. Um resultado desconhecido da IA usa source: ai e reason: insufficient_evidence.
{
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
},
"meta": {
"request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Interpretar a confiança e as evidências de correspondência
Uma confiança de 0.9 está em uma escala de 0 a 1. Para observed_frequency, ela significa a contagem dominante dividida pelo total selecionado no conjunto de dados; não é uma precisão do produto medida de ponta a ponta. Um valor model_reported é fornecido pela IA e não é calibrado em relação às frequências do conjunto de dados.
Escolha qualquer limite da sua aplicação usando seus próprios dados de avaliação e confidence_kind. Não compare diretamente valores do conjunto de dados e da IA como se medissem a mesma coisa. Na IA, match.name, match.scope e match.country são null porque nenhuma linha do conjunto de dados foi selecionada; match.method é model_inference.
Em nomes completos, um resultado do conjunto de dados pode vir de uma das partes, e não da string completa. data.input preserva o valor enviado; data.name descreve o nome retornado e data.match descreve o candidato e o escopo da consulta.
Decidir o que a sua aplicação deve fazer
Trate primeiro os erros da requisição e dos itens individuais e depois verifique result_status. Em uma previsão individual, leia data; em um lote, aplique a mesma decisão a data de cada item bem-sucedido. Preserve os resultados desconhecidos na sua aplicação em vez de forçar o rótulo male ou female.
| Resultado | O que significa | Tratamento recomendado |
|---|---|---|
| identified; gender: male ou female | A previsão retornou um gênero, com base no conjunto de dados ou na IA. | Aplique uma regra avaliada especificamente para esse confidence_kind; guarde source e as evidências da correspondência. |
| unknown; reason: not_found | Nenhuma entrada armazenada no conjunto de dados corresponde aos candidatos interpretados. | Mantenha gender como null. Uma nova requisição intencional com outras opções de IA é uma nova operação cobrada. |
| unknown; reason: no_name_candidate | A interpretação para o conjunto de dados não gerou um candidato de nome utilizável. | Preserve o null; verifique o tipo de entrada e o valor antes de escolher uma previsão adicional. |
| unknown; reason: ambiguous | A linha selecionada no conjunto de dados tem o mesmo número de ocorrências masculinas e femininas; sample_count ainda pode estar presente. | Não decida você mesmo qual gênero vale e não converta a confiança null em zero. |
| unknown; reason: insufficient_evidence | A IA concluiu a requisição sem evidências suficientes para retornar um gênero. | Trate como um resultado desconhecido concluído, não como um erro do provedor nem como candidato a novas tentativas automáticas. |
| Problem Details ou error de um item | A execução falhou, por exemplo com ai_upstream_error ou prediction_timeout. | Salve o código de erro e o ID da requisição, verifique a cobrança e siga as orientações sobre novas tentativas. |
Escolher limites com base na sua própria avaliação
Não existe um limite universal de confiança que torne uma previsão correta. Avalie observed_frequency e model_reported separadamente, com exemplos representativos do seu caso de uso, rotulados de forma independente. Uma frequência no conjunto de dados e um valor informado pela IA são sinais diferentes, mesmo quando ambos valem 0.9. Meça com que frequência a sua regra produz uma resposta e com que frequência essas respostas estão corretas; nos demais casos, preserve um resultado desconhecido ou preveja uma revisão manual.
Por exemplo, se result_status for identified, mas confidence_kind for model_reported, aplique a regra que você avaliou para a IA, não o limite do conjunto de dados. Se forceToGenderize foi usado, name: null junto com um gênero diferente de null é válido: um alias pode ser interpretado sem extrair um nome próprio real. Verifique gender e result_status, e não apenas name, para saber se a previsão deu uma resposta. O resultado continua sendo uma estimativa, não a confirmação da identidade de uma pessoa.