> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Modelli disponibili

Il campo `model` decide chi risponde, ed è obbligatorio. Gli id hanno la forma
`fornitore/modello`: `openai/gpt-5.4-mini`, `anthropic/claude-sonnet-5`,
`mistralai/mistral-small-4`, `openai/text-embedding-3-small`.

L'elenco non è uguale per tutti. Un modello è richiedibile quando fa parte del
catalogo dell'API, è disponibile nella regione che stai chiamando ed è abilitato
nella tua area di lavoro. Per questo il modo giusto di conoscerlo è chiederlo
all'API, non copiarlo da una pagina.

## Elencare i modelli

```bash
curl https://api.userbot.ai/api/eu/v1/models \
  -H "Authorization: Bearer $USERBOT_API_KEY"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-5.4-mini",
      "object": "model",
      "owned_by": "openai",
      "kind": "completion",
      "pricing": { "currency": "usd", "prompt": "…", "completion": "…" }
    },
    {
      "id": "openai/text-embedding-3-small",
      "object": "model",
      "owned_by": "openai",
      "kind": "embedding",
      "pricing": { "currency": "usd", "prompt": "…", "completion": "…" }
    }
  ]
}
```

L'`id` è esattamente la stringa da mettere in `model`. `kind` dice quale
endpoint lo accetta: `completion` per `/chat/completions` e `/responses`,
`embedding` per `/embeddings`. `pricing` è il listino del fornitore in dollari
per token, separato fra token in ingresso (`prompt`) e in uscita
(`completion`).

Gli stessi dati, in forma leggibile, stanno nella pagina **Sviluppatore**,
scheda **I modelli disponibili**: per ogni modello il nome, l'**API Model ID**
con il pulsante **Copia ID modello**, il fornitore, la regione, il tipo e i
prezzi nelle colonne **Input USD/1M** e **Output USD/1M**, cioè per milione di
token. Puoi filtrare per fornitore e per regione.

## Come si sceglie

Il criterio è il tipo di compito, non il nome del modello. Dentro ogni famiglia
i fornitori offrono una versione grande e una piccola (le sigle *mini*, *flash*,
*small*, *haiku*), e la differenza di prezzo fra le due si vede subito nelle
colonne dei prezzi.

| Compito                                                         | Cosa cercare                                                                  |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Classificare, estrarre campi, riformulare testi brevi           | Un modello piccolo. Costa una frazione degli altri e per questi compiti basta |
| Riassumere, rispondere su testi lunghi, scrivere testo standard | Un modello di fascia media                                                    |
| Ragionamento a più passaggi, codice, istruzioni complicate      | Un modello grande, con `reasoning_effort` se lo supporta                      |
| Ricerca semantica, confronto fra testi                          | Un modello con `kind` uguale a `embedding` → [Embeddings](/api-embeddings)    |

Il consiglio pratico: parti dal modello più economico che regge il compito e sali
solo quando vedi risposte sbagliate, non prima. Se il tuo servizio fa migliaia di
chiamate uguali, la differenza di prezzo si sente sulla spesa molto prima che
sulla qualità.

In chat esiste **Auto**, che sceglie da solo il modello. Via API non c'è: il tuo
codice conosce il compito meglio di qualsiasi regola automatica, quindi il
modello lo indichi tu.

## Se chiedi un modello che non c'è

La richiesta viene rifiutata, mai servita da un altro modello:

* su **Global** ricevi `400` con il messaggio `Unknown model: …`;
* su **EU** ricevi `451` con `region_not_allowed`.

Succede in quattro situazioni:

* **id scritto male.** Le versioni contano, e il fornitore davanti è
  obbligatorio: `gpt-5.4-mini` da solo non basta;
* **modello non disponibile in quella regione.** Controlla la colonna della
  regione, o chiama l'altro indirizzo di base;
* **modello spento dagli amministratori** nell'elenco **Modelli API disponibili**
  della tua area di lavoro: sparisce da `GET /models` e non si può più chiedere;
* **modello del tipo sbagliato**, per esempio un modello di embedding su
  `/chat/completions`.

L'elenco dei modelli dell'API è separato dal catalogo che i colleghi vedono nel
selettore della chat: un modello può essere in uno e non nell'altro. Chi
amministra decide quelli dell'API in [Chiavi API dell'area di lavoro](/chiavi-api-admin), e quelli della chat in [Modelli disponibili](/modelli-admin).

## Cambiare modello senza rimettere mano al codice

Tieni l'id in una variabile d'ambiente, non dentro le chiamate. Quando esce un
modello migliore o vuoi rientrare in un budget, cambi una riga di configurazione
invece di rifare un rilascio. Vale anche per gli ambienti: staging su un modello
economico, produzione su quello scelto.

Leggi `GET /models` all'avvio del servizio e controlla che il modello configurato
ci sia: se un amministratore lo spegne, te ne accorgi subito con un errore chiaro
invece che alla prima chiamata di un cliente.