Introduzione | Guida di Userbot

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
`POST /chat/completions`	Manda dei messaggi, ricevi la risposta. Streaming, strumenti, immagini e file → Completamenti chat
`POST /responses`	Lo stesso lavoro nel formato Responses di OpenAI → Responses
`POST /embeddings`	Trasforma un testo in un vettore numerico → 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:

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.

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

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

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

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 · Limiti e quote