AI mode and nicknames

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, creative usernames and handles 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 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"}}'

const response = await fetch("https://api.finowl.co/v1/gender/name", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FINOWL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Kiri", country: "NZ", options: { ai_mode: "always" } }),
});
const { data } = await response.json();

import os, requests

response = requests.post(
    "https://api.finowl.co/v1/gender/name",
    headers={"Authorization": f"Bearer {os.environ['FINOWL_API_KEY']}"},
    json={"name": "Kiri", "country": "NZ", "options": {"ai_mode": "always"}},
    timeout=30,
)
data = response.json()["data"]

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, aliases and handles that contain no real name.	3

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

Nicknames and handles

By default a username such as prenses or angelbaby_7 returns unknown, because it contains no real first name. forceToGenderize asks AI to read the meaning of the handle itself.

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

It works on all three endpoints and on batch items, and is most useful for usernames and email addresses.

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": "username", "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, social handles, usernames from sign-ups, 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.

Get started

Core concepts

Guides

AI mode and nicknames

Pricing at a glance

Turn AI on for a lookup

Every AI option

Nicknames and handles

In a batch

Reading an AI result

When to use AI

Good fit

Keep it off

Errors specific to AI

​Pricing at a glance

​Turn AI on for a lookup

​Every AI option

​Nicknames and handles

​In a batch

​Reading an AI result

​When to use AI

Good fit

Keep it off

​Errors specific to AI

Pricing at a glance

Turn AI on for a lookup

Every AI option

Nicknames and handles

In a batch

Reading an AI result

When to use AI

Errors specific to AI