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

# Introduzione

L'API di Userbot serve a chiamare i modelli dell'area di lavoro da un tuo
programma: un backend, uno script, il prodotto che stai costruendo. Le chiamate
si pagano come il resto dell'uso dell'area di lavoro e compaiono nei suoi
consumi, senza che nessuno apra il browser.

Il formato è quello di OpenAI. Se il tuo codice usa già l'SDK ufficiale di
OpenAI, cambi indirizzo di base e chiave e il resto resta com'è.

## Quando conviene usare l'API

Userbot ha tre modi di far lavorare l'AI. Il criterio per scegliere è chi fa
partire la richiesta e chi legge la risposta.

| Usi                | Quando                                                                                                     |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| L'interfaccia      | La richiesta la scrive una persona e la risposta la legge una persona                                      |
| Le **Automazioni** | Il compito parte da un orario o da un evento e resta dentro Userbot: documenti, integrazioni, approvazioni |
| L'API              | La richiesta nasce nel tuo software e la risposta serve dentro il tuo software                             |

In pratica: se il testo entra ed esce dal tuo codice, è API. Se qualcuno deve
leggerlo, approvarlo o riprenderlo in chat, è un'automazione.

## Cosa puoi chiamare

| Endpoint                 | A cosa serve                                                                                                                |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `GET /models`            | Elenca i modelli che puoi chiamare dalla tua area di lavoro, con il prezzo di listino → [Modelli disponibili](/api-modelli) |
| `POST /chat/completions` | Manda dei messaggi, ricevi la risposta. Streaming, strumenti, immagini e file → [Completamenti chat](/api-chat)             |
| `POST /responses`        | Lo stesso lavoro nel formato Responses di OpenAI → [Responses](/api-responses)                                              |
| `POST /embeddings`       | Trasforma un testo in un vettore numerico → [Embeddings](/api-embeddings)                                                   |

### Le due regioni

Gli endpoint sono gli stessi su due indirizzi di base. Scegli quello giusto una
volta, nella configurazione del client.

| Regione    | Indirizzo di base                  | Quando                                                                                        |
| ---------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
| **EU**     | `https://api.userbot.ai/api/eu/v1` | Le richieste restano nella regione europea. È la regione proposta negli esempi dentro Userbot |
| **Global** | `https://api.userbot.ai/api/v1`    | Ti servono modelli che in EU non ci sono                                                      |

L'elenco dei modelli può essere diverso fra le due regioni. Se su **EU** chiedi
un modello che lì non è disponibile, la richiesta viene rifiutata con `451`
invece di passare di nascosto a un'altra regione.

Una chiamata completa, per vederne la forma:

```bash
curl https://api.userbot.ai/api/eu/v1/chat/completions \
  -H "Authorization: Bearer $USERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "Rispondi in italiano, in una frase."},
      {"role": "user", "content": "Cosa contiene un preventivo?"}
    ]
  }'
```

## Cosa l'API non fa

L'API dà accesso ai modelli, non al resto di Userbot. Quello che segue **non** è
disponibile: se il tuo caso d'uso è in questo elenco, oggi si risolve con
un'automazione o dall'interfaccia.

* Libreria, ricerca nei documenti e **Conoscenza aziendale**: l'API non vede i
  vostri contenuti.
* Agenti, skill e prompt salvati: non si richiamano per nome.
* Avvio di workflow.
* Azioni sulle integrazioni. Con gli strumenti il modello ti dice
  quale funzione chiamare, ma a eseguirla è il tuo codice.
* Trascrizioni e sintesi vocale.

> **Info**
>
> Le chiamate API non creano conversazioni. Non compaiono nella cronologia, non
> si riaprono in chat e non ricordano nulla della chiamata precedente. La
> memoria della conversazione la tieni tu, rimandando i messaggi già scambiati a
> ogni richiesta.

## I passi per partire

#### Procurati una chiave

Se sviluppi per conto tuo, la crei dalla voce **Sviluppatore** nella barra
laterale. Se serve a un'integrazione dell'azienda che non deve dipendere da
una persona, la crea un amministratore in **Impostazioni › Funzionalità ›
Chiavi API**.

→ [Autenticazione e chiavi](/api-auth)

#### Scegli la regione e il modello

Il campo `model` è obbligatorio. Gli id hanno la forma `fornitore/modello`,
per esempio `openai/gpt-5.4-mini`: leggi quelli disponibili con `GET /models`
o nella scheda **I modelli disponibili** della pagina **Sviluppatore**.

→ [Modelli disponibili](/api-modelli)

#### Fai la prima chiamata

Manda la richiesta qui sopra con la tua chiave. Se ricevi del testo dentro
`choices[0].message.content`, il collegamento funziona.

→ [Completamenti chat](/api-chat)

Dentro Userbot trovi anche esempi pronti da copiare, in cURL e con gli SDK
OpenAI per JavaScript e Python: nella pagina **Sviluppatore**, sotto le tue
chiavi, e nella scheda **Documentazione** delle impostazioni **Chiavi API**.

## Cosa consuma

Ogni chiamata si paga in base ai token usati e al listino del modello. Chi paga
dipende dalla chiave: una chiave dell'area di lavoro scala il credito prepagato
dell'area di lavoro, una chiave personale consuma l'utilizzo di chi la possiede,
come fa la sua chat. Quando il credito o il budget è finito, la chiamata viene
rifiutata: l'API non passa mai a un modello più economico al posto tuo.

→ [Costi, budget e analytics](/api-costi) · [Limiti e quote](/api-limiti)