OpenWebUI API : discutez avec n'importe quelle page web

Si vous utilisez OpenWebUI, le plus dur est déjà fait. Vos modèles sont configurés et vos clés sont réunies au même endroit : peut-être Ollama sur un serveur maison, un ou deux fournisseurs cloud, et quelques modèles de workspace personnalisés que vous avez peaufinés.

Ce qu'OpenWebUI ne fait pas, en revanche, c'est fonctionner à l'intérieur des pages que vous consultez. Pour interroger un modèle sur l'article, le PDF ou la page de documentation que vous lisez, vous devez encore tout copier-coller dans un autre onglet.

C'est là qu'intervient SurfMind. OpenWebUI n'est pas qu'une interface de chat. Grâce à l'OpenWebUI API, il fait aussi office de serveur d'API, ce qui permet à SurfMind de s'en servir comme backend. Vous continuez à gérer vos modèles dans OpenWebUI, et SurfMind devient leur interface dans le navigateur.

Ce guide explique ce qu'est l'OpenWebUI API, comment elle s'articule avec SurfMind, les URLs exactes à coller et comment corriger les erreurs que l'on rencontre réellement.

OpenWebUI et SurfMind : des points communs, mais des rôles différents

À première vue, les deux ressemblent à des concurrents. Ce sont deux interfaces d'IA, toutes deux se connectent à de nombreux fournisseurs de LLM, et toutes deux vous permettent de discuter avec des modèles. Mais elles répondent à des usages différents :

OpenWebUI est un espace de travail d'IA auto-hébergé. SurfMind, c'est l'IA dans le navigateur que vous utilisez déjà. La ligne qui compte le plus est celle en gras. Comme OpenWebUI peut servir vos modèles via une API, les deux se complètent.

Pourquoi connecter OpenWebUI à SurfMind ?

Prenons une configuration typique. Vous avez OpenWebUI sur un serveur maison ou un petit VPS, et derrière :

• Llama, Qwen ou Gemma qui tournent en local via Ollama
• Des modèles GPT ou Claude via une clé API cloud
• Un modèle servi par vLLM sur votre propre GPU
• Quelques modèles de workspace que vous avez créés dans OpenWebUI, chacun avec son propre prompt système et ses réglages

Tout cela est accessible depuis la page de chat d'OpenWebUI. Mais vous voulez aussi ce qu'un assistant de navigateur fait bien : poser des questions sur la page en cours, résumer un long fil de discussion, comparer des informations entre plusieurs onglets ou rédiger une réponse sans quitter le site.

Vous pourriez ajouter de nouveau chaque fournisseur dans SurfMind, un par un : Ollama, puis votre clé OpenAI, puis votre endpoint vLLM. C'est fastidieux, vos clés se retrouvent en double, et les modèles de workspace que vous avez créés resteraient de côté.

Ou bien vous ajoutez une seule connexion : SurfMind → OpenWebUI. Tous les modèles visibles par OpenWebUI apparaissent dans le sélecteur de modèles de SurfMind. Vous continuez à gérer modèles, utilisateurs et permissions dans OpenWebUI, comme vous le faites déjà, et SurfMind ajoute la couche navigateur par-dessus.

C'est aussi un moyen pratique de partager une configuration en équipe. Si une équipe utilise une même instance OpenWebUI, chacun peut créer sa propre clé API et utiliser les modèles de l'équipe depuis son navigateur. Chacun conserve les permissions qu'il a dans OpenWebUI, et personne n'a besoin des clés des fournisseurs.

Étape 1 : créer une clé OpenWebUI API

Les clés API sont désactivées par défaut, il faut donc compter une minute la première fois.

Si vous êtes administrateur, activez les clés API :

1. Connectez-vous à OpenWebUI en tant qu'administrateur.
2. Allez dans Settings → Admin → Authentication.
3. Activez API Keys et cliquez sur Save.

Si vous n'êtes pas administrateur, demandez au vôtre de vous accorder la permission API Keys. Les administrateurs la règlent dans Admin Panel → Users → Groups, soit dans Default Permissions pour tout le monde, soit dans un groupe spécifique.

Ensuite, générez votre clé :

1. Cliquez sur votre icône de profil en bas à gauche.
2. Ouvrez Settings → Account.
3. Dans la section API keys, cliquez sur Show à côté de Secrets. La section est repliée par défaut : si la zone paraît vide, c'est normal.
4. Cliquez sur Create new secret key et copiez-la. Elle commence par sk-.

Quelques points à connaître, tirés de la documentation d'OpenWebUI sur les clés API :

• Une clé par compte. Créer une nouvelle clé remplace l'ancienne, qui cesse aussitôt de fonctionner. Si un autre outil utilise déjà votre clé, en créer une nouvelle pour SurfMind cassera cet outil. Un compte dédié, sans droits d'administrateur, pour SurfMind évite ce problème.
• La clé agit en votre nom. Elle voit les mêmes modèles et dispose des mêmes permissions que le compte qui l'a créée.
• N'utilisez pas le token JWT affiché aux administrateurs dans le même panneau. C'est le token de votre session navigateur, et il expire.

Étape 2 : ajouter OpenWebUI à SurfMind

Dans SurfMind, cliquez sur le nom du modèle en bas du panneau, puis sur Show all → Custom → Add Custom Models. Choisissez la configuration prédéfinie générique OpenAI-compatible et remplissez :

Si OpenWebUI tourne sur le même ordinateur que votre navigateur, l'hôte est généralement http://localhost:3000 (le mappage de port courant avec Docker) ou http://localhost:8080 (installation via pip ou directement sur la machine) :

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

Enregistrez, choisissez l'un de vos modèles OpenWebUI dans la liste, ouvrez n'importe quel article et demandez à SurfMind de le résumer.

Deux erreurs de chemin à éviter. Collez l'endpoint complet se terminant par /api/chat/completions, et non l'hôte seul ou /api. Le champ API URL de SurfMind n'ajoute pas le chemin à votre place. Et n'ajoutez /v1 nulle part : ni /api/v1/chat/completions ni /v1/chat/completions ne sont l'endpoint de chat d'OpenWebUI.

Dépannage : « les modèles se chargent mais le chat échoue »

C'est le problème le plus souvent signalé avec OpenWebUI, d'où cette section dédiée. Si les modèles apparaissent dans le menu déroulant, c'est que votre hôte, votre clé et votre chemin réseau fonctionnent. Le problème concerne donc spécifiquement la requête de chat. Vérifiez ces points dans l'ordre.

D'abord, testez en dehors de SurfMind. Un simple curl depuis un terminal vous indique si le problème vient d'OpenWebUI ou de vos réglages SurfMind. Remplacez l'hôte, la clé et l'id du modèle par les vôtres :

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"}]}'

Utilisez un id de modèle exactement tel qu'il apparaît dans la liste des modèles de SurfMind (ou dans GET /api/models). Si ça fonctionne, revérifiez les champs dans SurfMind. Si ça échoue aussi, l'erreur renvoyée vous oriente vers l'une des causes ci-dessous.

1. Le chemin du chat est incorrect. Models URL et API URL sont deux champs distincts : l'un peut être correct et l'autre non. Vérifiez que l'API URL se termine exactement par /api/chat/completions, sans /v1, sans slash final et sans faute de frappe.

2. Des restrictions d'endpoints bloquent le chat. Les administrateurs peuvent activer API Key Endpoint Restrictions, une liste blanche des routes que les clés API ont le droit d'appeler. Si elle inclut /api/models mais pas /api/chat/completions, c'est exactement ce qui se produit, généralement sous forme de 403. Demandez à votre administrateur d'ajouter /api/chat/completions.

3. Un réglage de modèle impose un mode de streaming. OpenWebUI propose un réglage Stream Chat Response, défini par modèle dans ses paramètres avancés ou comme valeur par défaut par l'administrateur dans Settings → Admin → Models. D'après la documentation d'OpenWebUI, ce réglage détermine si la réponse est diffusée en streaming quelle que soit la demande du client. Si un modèle est forcé dans un mode auquel le client ne s'attend pas, la réponse peut revenir dans un format que le client ne sait pas lire. Si le chat n'échoue qu'avec certains modèles, vérifiez ce réglage sur ceux-ci et remettez-le sur Default.

4. Un reverse proxy intercepte l'en-tête Authorization. Si OpenWebUI se trouve derrière une passerelle qui utilise Authorization pour sa propre authentification (basic auth, SSO, passerelle d'API), votre clé n'atteint jamais OpenWebUI. OpenWebUI accepte aussi la clé dans un en-tête personnalisé, x-api-key par défaut. Dans ce cas, choisissez x-api-key comme API Key Header dans SurfMind. Si votre administrateur a renommé l'en-tête avec CUSTOM_API_KEY_HEADER, le proxy doit laisser passer cet en-tête.

5. L'id du modèle ne correspond pas. Choisissez dans le menu déroulant plutôt que de saisir. Les ids OpenWebUI des modèles Ollama incluent le tag (llama3.2:latest), et les modèles de workspace utilisent l'id que vous leur avez donné, pas leur nom affiché.

6. Le fournisseur derrière OpenWebUI est en échec. Quand le fournisseur en amont rejette une requête, OpenWebUI transmet son code d'état tel quel. Un 429 provient de la limite de débit du fournisseur, pas d'OpenWebUI ni de SurfMind. Essayez le même modèle dans le chat d'OpenWebUI. S'il échoue là aussi, le problème se situe en amont.

Autres erreurs, en bref

Pour les règles générales qui s'appliquent à tous les endpoints personnalisés (ports, http vs https, URL de base vs endpoint complet), consultez notre guide de connexion d'une IA personnalisée.

OpenWebUI, SurfMind ou les deux ?

Il n'est pas question de choisir l'un ou l'autre.

• OpenWebUI seul est idéal si l'essentiel de votre usage de l'IA consiste en de longues conversations dans un onglet dédié : discuter avec les documents de vos bases de connaissances, faire tourner des pipelines, gérer des modèles pour une équipe.
• SurfMind seul est idéal si l'essentiel de votre usage de l'IA part de ce qui s'affiche à l'écran, et que connecter directement des fournisseurs ou un moteur local comme Ollama vous convient.
• Les deux ont du sens quand vous avez investi dans une configuration OpenWebUI et voulez en profiter sur chaque page sans tout configurer deux fois.

La répartition est simple : OpenWebUI gère vos modèles, et SurfMind les met au travail dans le navigateur.

Questions fréquentes

OpenWebUI a-t-il une API ? Oui. L'OpenWebUI API est une API REST authentifiée par tokens Bearer. Les deux endpoints dont la plupart des outils ont besoin sont GET /api/models pour lister les modèles et POST /api/chat/completions pour le chat, qui accepte les requêtes au format OpenAI.

L'OpenWebUI API est-elle compatible OpenAI ? Le format des requêtes et des réponses l'est. Les chemins, eux, ne sont pas les chemins standard : OpenWebUI utilise /api/chat/completions au lieu de /v1/chat/completions. Tout client qui vous permet de définir l'URL complète de l'endpoint, comme SurfMind, peut l'utiliser.

Où trouver ma clé OpenWebUI API ? Allez dans Settings → Account → API keys, cliquez sur Show, puis sur Create new secret key. Si la section n'apparaît pas, un administrateur doit activer API Keys dans Settings → Admin → Authentication et accorder à votre compte la permission API Keys.

Puis-je utiliser mes modèles de workspace OpenWebUI dans SurfMind ? Oui. Les modèles de workspace sont listés par /api/models comme n'importe quel autre modèle. Quand vous les appelez, OpenWebUI applique leurs réglages enregistrés.

Connecter OpenWebUI envoie-t-il mes données aux serveurs de SurfMind ? Avec un endpoint personnalisé, SurfMind envoie les requêtes à l'URL que vous avez configurée, ici votre serveur OpenWebUI. Votre serveur OpenWebUI les transmet ensuite au modèle que vous avez choisi. Si ce modèle tourne en local, le contenu de la page reste sur du matériel que vous contrôlez.

Est-ce gratuit ? Oui. Les endpoints personnalisés dans SurfMind ne coûtent rien et nous n'imposons aucune limite d'utilisation. Vous ne payez que ce que facturent vos propres fournisseurs, c'est-à-dire rien pour les modèles locaux.

Toujours bloqué ?

Si le test curl fonctionne et que SurfMind refuse toujours de discuter avec vos modèles OpenWebUI, écrivez-nous à wave@surfmind.ai. Indiquez votre API URL (sans la clé), le code d'état HTTP, et précisez si l'échec touche certains modèles ou tous. Les configurations auto-hébergées varient énormément, et ces retours nous aident à faire fonctionner SurfMind sans accroc avec elles.

Obtenir SurfMind →