> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finowl.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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, 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](/concepts/credits).

## Turn AI on for a lookup

Set `options.ai_mode` to `always` on any gender endpoint.

<CodeGroup>
  ```bash cURL theme={null}
  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"}}'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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"]
  ```
</CodeGroup>

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

```json theme={null}
{ "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Good fit" icon="check">
    Rare or international names, nicknames, social handles, usernames from sign-ups, and lists where fewer `unknown` results matter more than cost.
  </Card>

  <Card title="Keep it off" icon="xmark">
    Large lists of ordinary first names, where the dataset already answers, and workflows where every answer must be traceable to real-world counts.
  </Card>
</CardGroup>

<Warning>
  A prediction is a statistical guess, not how a person identifies. Use it for aggregate insight and low-stakes personalization only. See [Interpreting predictions](/guides/interpreting-predictions).
</Warning>

## 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](https://app.finowl.co/sandbox).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.