Modelli disponibili | Guida di Userbot

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

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

{
  "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

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, e quelli della chat in Modelli disponibili.

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.