OpenWebUI API: usa i tuoi modelli su qualsiasi pagina web

Se usi OpenWebUI, il grosso del lavoro l'hai già fatto. I tuoi modelli sono configurati e le chiavi stanno tutte in un unico posto: magari Ollama su un server di casa, uno o due provider cloud e qualche modello workspace personalizzato che hai messo a punto.

Quello che OpenWebUI non fa è lavorare dentro le pagine che stai visitando. Se vuoi chiedere a un modello qualcosa sull'articolo, sul PDF o sulla pagina di documentazione che hai davanti, devi ancora copiarlo e incollarlo in un'altra scheda.

Ed è qui che entra in gioco SurfMind. OpenWebUI non è solo un'interfaccia di chat: tramite l'OpenWebUI API funziona anche da server API, quindi SurfMind può usarlo come backend. Tu continui a gestire i modelli in OpenWebUI, e SurfMind diventa il loro front end nel browser.

In questa guida vediamo cos'è l'OpenWebUI API, che rapporto ha con SurfMind, gli URL esatti da incollare e come risolvere gli errori in cui si inciampa davvero.

OpenWebUI e SurfMind: simili in apparenza, ruoli diversi

A prima vista sembrano concorrenti. Sono entrambi interfacce per l'IA, si collegano entrambi a tanti provider di LLM e con entrambi chatti con i modelli. Rispondono però a esigenze diverse:

OpenWebUI è un ambiente di lavoro IA self-hosted. SurfMind è l'IA dentro il browser che usi già. La riga che conta di più è quella in grassetto: siccome OpenWebUI può servire i tuoi modelli tramite API, i due si completano a vicenda.

Perché collegare OpenWebUI a SurfMind?

Immagina una configurazione tipica. Hai OpenWebUI su un server di casa o su un piccolo VPS, e dietro:

• Llama, Qwen o Gemma in locale tramite Ollama
• Modelli GPT o Claude tramite una chiave API cloud
• Un modello servito da vLLM sulla tua GPU
• Qualche modello workspace creato in OpenWebUI, ognuno con il suo system prompt e le sue impostazioni

Tutto questo è raggiungibile dalla pagina di chat di OpenWebUI. Ora però vuoi anche quello che un assistente nel browser fa bene: fare domande sulla pagina corrente, riassumere una lunga discussione, confrontare informazioni tra schede o scrivere una risposta senza lasciare il sito.

Potresti aggiungere di nuovo ogni provider a SurfMind, uno per uno: Ollama, poi la chiave OpenAI, poi l'endpoint vLLM. È noioso, duplica le tue chiavi e i modelli workspace che hai creato resterebbero fuori.

Oppure aggiungi un solo collegamento: SurfMind → OpenWebUI. Ogni modello visibile a OpenWebUI compare nel selettore dei modelli di SurfMind. Modelli, utenti e permessi continui a gestirli in OpenWebUI, come fai già, e SurfMind ti permette di usarli direttamente nel browser.

È anche un modo pratico per condividere una configurazione con il team. Se un team usa una sola istanza di OpenWebUI, ognuno può creare la propria chiave API e usare i modelli del team dal proprio browser, con gli stessi permessi che ha in OpenWebUI. E nessuno ha bisogno delle chiavi dei provider.

Passaggio 1: crea una chiave API di OpenWebUI

Le chiavi API sono disattivate per impostazione predefinita, quindi la prima volta serve un minuto.

Se sei l'amministratore, attiva le chiavi API:

1. Accedi a OpenWebUI come amministratore.
2. Vai su Settings → Admin → Authentication.
3. Attiva API Keys e clicca su Save.

Se non sei amministratore, chiedi al tuo admin di darti il permesso per la funzione API Keys. Gli admin lo impostano in Admin Panel → Users → Groups, in Default Permissions per tutti oppure in un gruppo specifico.

Poi genera la tua chiave:

1. Clicca sull'icona del profilo in basso a sinistra.
2. Apri Settings → Account.
3. Nella sezione API keys, clicca su Show accanto a Secrets. La sezione è compressa per impostazione predefinita, quindi è normale che qui sembri vuota.
4. Clicca su Create new secret key e copiala. Inizia con sk-.

Qualche dettaglio utile, dalla documentazione di OpenWebUI sulle chiavi API:

• Una chiave per account. Creare una nuova chiave sostituisce quella vecchia, che smette subito di funzionare. Se un altro strumento usa già la tua chiave, crearne una nuova per SurfMind lo manderà in tilt. Un account dedicato non amministratore per SurfMind evita il problema.
• La chiave agisce a nome tuo. Vede gli stessi modelli e ha gli stessi permessi dell'account che l'ha creata.
• Non usare il token JWT che gli admin vedono nello stesso pannello. È il token della tua sessione nel browser, e scade.

Passaggio 2: aggiungi OpenWebUI a SurfMind

In SurfMind, clicca sul nome del modello in fondo al pannello, poi su Show all → Custom → Add Custom Models. Scegli la configurazione predefinita generica OpenAI-compatible e compila:

Se OpenWebUI gira sullo stesso computer del browser, di solito l'host è http://localhost:3000 (la mappatura di porta più comune con Docker) oppure http://localhost:8080 (installazione con pip o bare-metal):

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models

Salva, scegli uno dei tuoi modelli OpenWebUI dall'elenco, apri un articolo qualsiasi e chiedi a SurfMind di riassumerlo.

Due errori di percorso da evitare. Incolla l'endpoint completo che termina con /api/chat/completions, non l'host da solo o /api: il campo API URL di SurfMind non aggiunge il percorso al posto tuo. E non aggiungere /v1 da nessuna parte. /api/v1/chat/completions e /v1/chat/completions non sono l'endpoint di chat di OpenWebUI.

Risoluzione dei problemi: "i modelli si caricano ma la chat non funziona"

È la segnalazione più frequente su OpenWebUI, quindi merita una sezione tutta sua. Se i modelli compaiono nel menu a discesa, host, chiave e percorso di rete funzionano: a non andare è qualcosa di specifico della richiesta di chat. Controlla questi punti nell'ordine.

Prima di tutto, fai una prova fuori da SurfMind. Un rapido curl dal terminale ti dice se il problema sta in OpenWebUI o nelle impostazioni di SurfMind. Sostituisci host, chiave e id del modello con i tuoi:

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

Usa l'id del modello esattamente come compare nell'elenco dei modelli di SurfMind (o in GET /api/models). Se funziona, ricontrolla i campi in SurfMind. Se fallisce anche così, l'errore restituito ti indirizza verso una delle cause qui sotto.

1. Il percorso della chat è sbagliato. Models URL e API URL sono campi separati, quindi uno può essere giusto e l'altro no. Verifica che l'API URL termini esattamente con /api/chat/completions, senza /v1, senza slash finale e senza errori di battitura.

2. Le restrizioni sugli endpoint bloccano la chat. Gli admin possono attivare API Key Endpoint Restrictions, un elenco delle route che le chiavi API possono chiamare. Se contiene /api/models ma non /api/chat/completions, succede proprio questo, di solito con un 403. Chiedi al tuo admin di aggiungere /api/chat/completions.

3. Un'impostazione del modello forza lo streaming. OpenWebUI ha un'impostazione Stream Chat Response, definita per singolo modello nei parametri avanzati oppure come valore predefinito dell'admin in Settings → Admin → Models. Secondo la documentazione di OpenWebUI, questa impostazione decide se la risposta viene inviata in streaming a prescindere da ciò che ha chiesto il client. Se un modello è forzato in una modalità che il client non si aspetta, la risposta può arrivare in un formato che il client non riesce a leggere. Se la chat fallisce solo con certi modelli, controlla questa impostazione su di loro e riportala su Default.

4. Un reverse proxy si mangia l'header Authorization. Se OpenWebUI sta dietro un gateway che usa Authorization per il proprio login (basic auth, SSO, un API gateway), la tua chiave non arriva mai a OpenWebUI. OpenWebUI accetta la chiave anche in un header personalizzato, x-api-key per impostazione predefinita. In questo caso scegli x-api-key come API Key Header in SurfMind. Se il tuo admin ha rinominato l'header con CUSTOM_API_KEY_HEADER, il proxy deve lasciar passare quell'header.

5. L'id del modello non corrisponde. Sceglilo dal menu a discesa invece di digitarlo. Per i modelli Ollama, gli id di OpenWebUI includono il tag (llama3.2:latest), mentre i modelli workspace usano l'id che gli hai assegnato, non il nome visualizzato.

6. Il provider dietro OpenWebUI sta fallendo. Quando il provider a monte rifiuta una richiesta, OpenWebUI ne inoltra il codice di stato. Un 429 viene dal limite di frequenza del provider, non da OpenWebUI né da SurfMind. Prova lo stesso modello nella chat di OpenWebUI: se fallisce anche lì, il problema è a monte.

Altri errori in breve

Per le regole generali valide per qualsiasi endpoint personalizzato (porte, http vs https, URL di base vs endpoint completo), vedi la nostra guida per collegare un'IA personalizzata.

Meglio OpenWebUI, SurfMind o tutti e due?

Non bisogna per forza scegliere.

• Solo OpenWebUI è perfetto se usi l'IA soprattutto per lunghe conversazioni in una scheda dedicata: chattare con i documenti delle tue knowledge base, eseguire pipeline, gestire modelli per un team.
• Solo SurfMind è perfetto se il tuo uso dell'IA parte quasi sempre da ciò che hai sullo schermo, e ti va bene collegare direttamente i provider o un runner locale come Ollama.
• Tutti e due ha senso quando hai investito in una configurazione OpenWebUI e vuoi averla a disposizione su ogni pagina senza configurare tutto due volte.

La divisione dei compiti è semplice: OpenWebUI gestisce i tuoi modelli, SurfMind li mette al lavoro nel browser.

Domande frequenti

OpenWebUI ha un'API? Sì. L'OpenWebUI API è un'API REST con autenticazione tramite token Bearer. I due endpoint che servono alla maggior parte degli strumenti sono GET /api/models per elencare i modelli e POST /api/chat/completions per la chat, che accetta richieste in stile OpenAI.

L'OpenWebUI API è compatibile con OpenAI? Il formato di richieste e risposte sì. I percorsi invece non sono quelli standard: OpenWebUI usa /api/chat/completions al posto di /v1/chat/completions. Qualsiasi client che ti permetta di impostare l'URL completo dell'endpoint, come SurfMind, può usarla.

Dove trovo la mia chiave API di OpenWebUI? Vai su Settings → Account → API keys, clicca su Show, poi su Create new secret key. Se la sezione non c'è, un admin deve attivare API Keys in Settings → Admin → Authentication e dare al tuo account il permesso API Keys.

Posso usare i miei modelli workspace di OpenWebUI in SurfMind? Sì. I modelli workspace vengono elencati da /api/models come qualsiasi altro modello. Quando li chiami, OpenWebUI applica le impostazioni che hai salvato.

Collegando OpenWebUI, i miei dati passano dai server di SurfMind? Con un endpoint personalizzato, SurfMind invia le richieste all'URL che hai configurato, in questo caso il tuo server OpenWebUI. È poi il tuo server OpenWebUI a inoltrarle al modello che hai scelto. Se quel modello gira in locale, il contenuto della pagina resta su hardware che controlli tu.

È gratis? Sì. Gli endpoint personalizzati in SurfMind non costano nulla e non hanno limiti di utilizzo da parte nostra. Paghi solo quello che ti fanno pagare i tuoi provider, cioè niente per i modelli locali.

Ancora bloccato?

Se il test con curl funziona ma SurfMind continua a non chattare con i tuoi modelli OpenWebUI, scrivici a wave@surfmind.ai. Indica il tuo API URL (senza la chiave), il codice di stato HTTP e se falliscono solo alcuni modelli o tutti. Le configurazioni self-hosted variano parecchio, e queste segnalazioni ci aiutano a far funzionare SurfMind senza intoppi con tutte.

Ottieni SurfMind →