AI mode and nicknames

Turn on AI for harder names, nicknames and handles, what it costs and how to read AI results.

Finowl intelligence answers most gender lookups from a large dataset of real names. AI mode adds a language model for inputs the dataset cannot place, such as rare names, nicknames and names in other scripts.

Pricing at a glance

Request	Credits
Default lookup, with no AI option	1
options.ai_mode: "always"	3
forceToGenderize: true	3
Batch item	1, or 3 when that item sets either option

A request that asks for AI costs 3 credits even when the dataset ends up answering. Lookups that fail and were not billed by our provider are free. See Credits and billing.

Turn AI on for a lookup

Set options.ai_mode to always on any gender endpoint.

cURL

curl https://api.finowl.co/v1/gender/name \
  -H "Authorization: Bearer $FINOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kiri", "country": "NZ", "options": {"ai_mode": "always"}}'

Every AI option

Setting	What happens	Credits
No option (default for single lookups)	Dataset first. If it has no answer, AI may fill the gap.	1
options.ai_mode: "off"	Dataset only. More unknown results, fully predictable. Default for batch items.	1
options.ai_mode: "always"	AI on every lookup.	3
forceToGenderize: true	Dataset first, then AI reads nicknames and aliases that are not a real first name.	3

forceToGenderize cannot be combined with ai_mode off or always. That combination returns 400 invalid_input and costs nothing.

Nicknames

By default a nickname such as prenses returns unknown, because it is not a real first name. forceToGenderize asks AI to read the meaning of the nickname itself.

{ "name": "prenses", "country": "TR", "forceToGenderize": true }

It works on both endpoints and on batch items, and is most useful for nicknames and email addresses whose local part is not a name.

In a batch

Each item chooses its own settings, and each is priced separately. This batch costs 1 + 3 + 3 = 7 credits:

{
  "items": [
    { "id": "a", "type": "name", "value": "Jane" },
    { "id": "b", "type": "name", "value": "Kiri", "options": { "ai_mode": "always" } },
    { "id": "c", "type": "name", "value": "prenses", "forceToGenderize": true }
  ]
}

Batch items default to ai_mode: "off". Set options.ai_mode to fallback on an item to let AI fill gaps for 1 credit, as single lookups do. The whole batch must be covered by your balance before it runs.

Reading an AI result

AI results use the same response shape. Check source and confidence_kind to tell them apart:

{
  "data": {
    "result_status": "identified",
    "gender": "female",
    "name": "kiri",
    "confidence": 0.82,
    "confidence_kind": "model_reported",
    "sample_count": null,
    "source": "ai",
    "country": "NZ",
    "reason": null
  }
}

Field	Dataset result	AI result
source	dataset	ai
confidence_kind	observed_frequency, from real counts	model_reported, the model’s own estimate
sample_count	Number of supporting records	null

A model-reported confidence is not a measured frequency. Treat AI answers as lower certainty than dataset answers with the same number. When AI cannot decide, the result is unknown with reason: "insufficient_evidence".

When to use AI

Good fit

Rare or international names, nicknames, emails without a clear name, and lists where fewer unknown results matter more than cost.

Keep it off

Large lists of ordinary first names, where the dataset already answers, and workflows where every answer must be traceable to real-world counts.

A prediction is a statistical guess, not how a person identifies. Use it for aggregate insight and low-stakes personalization only. See Interpreting predictions.

Errors specific to AI

Status	Code	What to do
400	invalid_input	You combined forceToGenderize with ai_mode off or always. Remove one. Not charged.
503	provider_unavailable	AI is temporarily unavailable. Retry later, or send the request without AI options. Free when it was not billed.

You can try every option, with its price shown before you run it, in the Sandbox.