OpenWebUI API: Deine Modelle auf jeder Webseite nutzen

Wenn du OpenWebUI betreibst, ist die eigentliche Arbeit schon erledigt. Deine Modelle sind eingerichtet und deine Schlüssel liegen an einem Ort – vielleicht mit Ollama auf einem Heimserver, ein, zwei Cloud-Anbietern und ein paar eigenen Workspace-Modellen, die du feinjustiert hast.

OpenWebUI steht dir allerdings nicht direkt auf den Webseiten zur Verfügung, die du gerade liest. Wenn du ein Modell etwas zu dem Artikel, dem PDF oder der Doku-Seite fragen willst, die du liest, kopierst du den Inhalt immer noch in einen anderen Tab.

Genau hier kommt SurfMind ins Spiel. OpenWebUI ist nicht nur eine Chat-Oberfläche. Über die OpenWebUI API arbeitet es auch als API-Server, und SurfMind kann es deshalb als Backend nutzen. Du verwaltest deine Modelle weiter in OpenWebUI, und SurfMind wird zum Browser-Frontend dafür.

Dieser Leitfaden erklärt, was die OpenWebUI API ist, wie sie mit SurfMind zusammenspielt, welche URLs du genau einfügen musst und wie du die Fehler behebst, die in der Praxis tatsächlich auftreten.

OpenWebUI und SurfMind: auf den ersten Blick ähnlich, aber mit unterschiedlichen Aufgaben

Auf den ersten Blick wirken die beiden wie Konkurrenten. Beide sind KI-Oberflächen, beide verbinden sich mit vielen LLM-Anbietern, und mit beiden chattest du mit Modellen. Sie sind allerdings für unterschiedliche Einsatzbereiche gedacht:

OpenWebUI ist ein selbst gehosteter KI-Arbeitsplatz. SurfMind ist KI direkt in dem Browser, den du sowieso nutzt. Entscheidend ist die fett markierte Zeile: Weil OpenWebUI deine Modelle über eine API bereitstellen kann, ergänzen sich die beiden.

Warum OpenWebUI mit SurfMind verbinden?

Stell dir ein typisches Setup vor. Du hast OpenWebUI auf einem Heimserver oder einem kleinen VPS laufen, und dahinter:

• Llama, Qwen oder Gemma, lokal über Ollama
• GPT- oder Claude-Modelle über einen Cloud-API-Schlüssel
• Ein Modell, das vLLM auf deiner eigenen GPU bereitstellt
• Ein paar Workspace-Modelle, die du in OpenWebUI gebaut hast, jedes mit eigenem System-Prompt und eigenen Einstellungen

All das erreichst du über die Chat-Seite von OpenWebUI. Jetzt willst du aber auch das, was ein Browser-Assistent gut kann: Fragen zur aktuellen Seite stellen, einen langen Thread zusammenfassen, Informationen über mehrere Tabs hinweg vergleichen oder eine Antwort entwerfen, ohne die Seite zu verlassen.

Du könntest jeden Anbieter einzeln in SurfMind neu anlegen: erst Ollama, dann deinen OpenAI-Schlüssel, dann deinen vLLM-Endpunkt. Das ist mühsam, du musst deine Schlüssel an zwei Stellen verwalten, und deine selbst gebauten Workspace-Modelle wären trotzdem nicht dabei.

Oder du legst eine einzige Verbindung an: SurfMind → OpenWebUI. Jedes Modell, das OpenWebUI sieht, taucht dann in der Modellauswahl von SurfMind auf. Modelle, Nutzer und Berechtigungen verwaltest du weiter in OpenWebUI, wie gewohnt, und SurfMind macht die Modelle direkt im Browser zugänglich.

So lässt sich eine gemeinsame Konfiguration auch bequem im Team nutzen. Betreibt ein Team eine gemeinsame OpenWebUI-Instanz, kann sich jede Person einen eigenen API-Schlüssel erstellen und die Modelle des Teams im Browser nutzen. Alle haben dieselben Berechtigungen wie in OpenWebUI, und niemand braucht die Schlüssel der Anbieter selbst.

Schritt 1: Einen API-Schlüssel in OpenWebUI erstellen

API-Schlüssel sind standardmäßig deaktiviert, beim ersten Mal dauert es also eine Minute.

Wenn du Admin bist, aktiviere API-Schlüssel:

1. Melde dich als Administrator bei OpenWebUI an.
2. Geh zu Settings → Admin → Authentication.
3. Schalte API Keys ein und klick auf Save.

Wenn du kein Admin bist, bitte deinen Admin, dir die Berechtigung API Keys zu geben. Admins legen sie unter Admin Panel → Users → Groups fest, entweder in Default Permissions für alle oder in einer bestimmten Gruppe.

Dann erstellst du deinen Schlüssel:

1. Klick unten links auf dein Profilsymbol.
2. Öffne Settings → Account.
3. Klick im Abschnitt API keys neben Secrets auf Show. Der Abschnitt ist standardmäßig eingeklappt, ein scheinbar leerer Bereich ist hier also normal.
4. Klick auf Create new secret key und kopiere ihn. Er beginnt mit sk-.

Ein paar Dinge, die du laut der OpenWebUI-Doku zu API-Schlüsseln wissen solltest:

• Ein Schlüssel pro Konto. Ein neuer Schlüssel ersetzt den alten, und der alte funktioniert sofort nicht mehr. Wenn ein anderes Tool deinen Schlüssel schon nutzt, legst du dieses Tool lahm, sobald du für SurfMind einen neuen erstellst. Ein eigenes Nicht-Admin-Konto nur für SurfMind umgeht das Problem.
• Der Schlüssel handelt in deinem Namen. Er sieht dieselben Modelle und hat dieselben Berechtigungen wie das Konto, das ihn erstellt hat.
• Verwende nicht das JWT-Token, das Admins im selben Bereich angezeigt wird. Das ist das Sitzungstoken deines Browsers, und es läuft ab.

Schritt 2: OpenWebUI zu SurfMind hinzufügen

Klick in SurfMind unten im Panel auf den Modellnamen und dann auf Show all → Custom → Add Custom Models. Wähl die allgemeine Vorlage OpenAI-compatible und trag Folgendes ein:

Läuft OpenWebUI auf demselben Rechner wie dein Browser, ist der Host meist http://localhost:3000 (das übliche Port-Mapping bei Docker) oder http://localhost:8080 (Installation per pip oder direkt auf dem System):

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

Speichern, eines deiner OpenWebUI-Modelle aus der Liste wählen, einen beliebigen Artikel öffnen und SurfMind bitten, ihn zusammenzufassen.

Zwei Pfad-Fehler, die du vermeiden solltest. Füge den vollständigen Endpunkt ein, der auf /api/chat/completions endet, nicht nur den Host oder /api. Das API-URL-Feld von SurfMind hängt den Pfad nicht für dich an. Und füg nirgendwo /v1 hinzu. /api/v1/chat/completions und /v1/chat/completions sind nicht der Chat-Endpunkt von OpenWebUI.

Fehlerbehebung: „Modelle laden, aber der Chat schlägt fehl“

Das ist die häufigste Meldung rund um OpenWebUI, deshalb bekommt sie einen eigenen Abschnitt. Wenn sich das Modell-Dropdown füllt, funktionieren Host, Schlüssel und Netzwerkweg. Es hakt also an etwas, das speziell die Chat-Anfrage betrifft. Geh die folgenden Punkte der Reihe nach durch.

Teste zuerst außerhalb von SurfMind. Ein kurzer curl-Aufruf im Terminal zeigt dir, ob das Problem bei OpenWebUI oder in deinen SurfMind-Einstellungen liegt. Ersetze Host, Schlüssel und Modell-ID durch deine eigenen:

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

Verwende die Modell-ID genau so, wie sie in der Modellliste von SurfMind (oder in GET /api/models) steht. Funktioniert das, prüf die Felder in SurfMind noch einmal. Schlägt es auch hier fehl, verrät dir die zurückgegebene Fehlermeldung, welche der folgenden Ursachen zutrifft.

1. Der Chat-Pfad ist falsch. Models URL und API URL sind getrennte Felder, das eine kann also stimmen und das andere nicht. Prüf, ob die API URL exakt auf /api/chat/completions endet – ohne /v1, ohne abschließenden Schrägstrich und ohne Tippfehler.

2. Endpunkt-Beschränkungen blockieren den Chat. Admins können API Key Endpoint Restrictions aktivieren, eine Allowlist der Routen, die API-Schlüssel aufrufen dürfen. Steht dort /api/models, aber nicht /api/chat/completions, bekommst du genau dieses Symptom, meist als 403. Bitte deinen Admin, /api/chat/completions hinzuzufügen.

3. Eine Modelleinstellung erzwingt einen Streaming-Modus. OpenWebUI hat die Einstellung Stream Chat Response, die pro Modell in den erweiterten Parametern oder als Admin-Standard unter Settings → Admin → Models gesetzt wird. Laut der OpenWebUI-Doku entscheidet diese Einstellung, ob die Antwort gestreamt wird – unabhängig davon, was der Client angefordert hat. Wird ein Modell in einen Modus gezwungen, den der Client nicht erwartet, kann die Antwort in einem Format zurückkommen, mit dem der Client nichts anfangen kann. Schlägt der Chat nur bei bestimmten Modellen fehl, prüf diese Einstellung bei ihnen und setz sie wieder auf Default.

4. Ein Reverse Proxy verschluckt den Authorization-Header. Sitzt OpenWebUI hinter einem Gateway, das Authorization für seinen eigenen Login nutzt (Basic Auth, SSO, ein API-Gateway), kommt dein Schlüssel nie bei OpenWebUI an. OpenWebUI akzeptiert den Schlüssel aber auch in einem eigenen Header, standardmäßig x-api-key. Wähl in diesem Fall x-api-key als API Key Header in SurfMind. Hat dein Admin den Header mit CUSTOM_API_KEY_HEADER umbenannt, muss der Proxy genau diesen Header durchreichen.

5. Die Modell-ID stimmt nicht. Wähl aus dem Dropdown, statt zu tippen. Bei Ollama-Modellen enthalten die IDs in OpenWebUI den Tag (llama3.2:latest), und Workspace-Modelle verwenden die ID, die du ihnen gegeben hast, nicht ihren Anzeigenamen.

6. Der Anbieter hinter OpenWebUI streikt. Lehnt der vorgelagerte Anbieter eine Anfrage ab, reicht OpenWebUI dessen Statuscode durch. Ein 429 kommt vom Rate Limit des Anbieters, nicht von OpenWebUI oder SurfMind. Probier dasselbe Modell im Chat von OpenWebUI selbst aus. Schlägt es auch dort fehl, liegt das Problem beim Anbieter.

Weitere Fehler im Schnelldurchlauf

Die allgemeinen Regeln, die für jeden eigenen Endpunkt gelten (Ports, http vs. https, Basis-URL vs. vollständiger Endpunkt), findest du in unserem Leitfaden zum Verbinden eigener KI-Modelle.

OpenWebUI, SurfMind oder beides?

Das ist keine Entweder-oder-Frage.

• Nur OpenWebUI ist ideal, wenn du KI vor allem für lange Unterhaltungen in einem eigenen Tab nutzt: mit Dokumenten aus deinen Wissensdatenbanken chatten, Pipelines laufen lassen, Modelle für ein Team verwalten.
• Nur SurfMind ist ideal, wenn deine KI-Nutzung meist bei dem anfängt, was gerade auf deinem Bildschirm ist, und du Anbieter oder einen lokalen Runner wie Ollama gern direkt verbindest.
• Beides lohnt sich, wenn du schon Zeit in dein OpenWebUI-Setup gesteckt hast und es auf jeder Seite nutzen willst, ohne alles doppelt einzurichten.

Die Aufteilung ist einfach: OpenWebUI verwaltet deine Modelle, SurfMind setzt sie im Browser ein.

Häufige Fragen

Hat OpenWebUI eine API? Ja. Die OpenWebUI API ist eine REST-API mit Authentifizierung per Bearer-Token. Die beiden Endpunkte, die die meisten Tools brauchen, sind GET /api/models zum Auflisten der Modelle und POST /api/chat/completions für den Chat, der Anfragen im OpenAI-Format akzeptiert.

Ist die OpenWebUI API OpenAI-kompatibel? Das Anfrage- und Antwortformat schon. Die Pfade sind aber nicht die üblichen: OpenWebUI nutzt /api/chat/completions statt /v1/chat/completions. Jeder Client, bei dem du die vollständige Endpunkt-URL selbst festlegen kannst, wie SurfMind, kommt damit klar.

Wo finde ich meinen API-Schlüssel für OpenWebUI? Geh zu Settings → Account → API keys, klick auf Show und dann auf Create new secret key. Fehlt der Abschnitt, muss ein Admin API Keys unter Settings → Admin → Authentication aktivieren und deinem Konto die Berechtigung API Keys geben.

Kann ich meine Workspace-Modelle aus OpenWebUI in SurfMind nutzen? Ja. Workspace-Modelle werden von /api/models wie jedes andere Modell aufgelistet. Wenn du sie aufrufst, wendet OpenWebUI ihre gespeicherten Einstellungen an.

Schickt die Verbindung mit OpenWebUI meine Daten an die Server von SurfMind? Bei einem eigenen Endpunkt schickt SurfMind die Anfragen an die URL, die du eingetragen hast – hier also an deinen OpenWebUI-Server. Der leitet sie an das Modell weiter, das du ausgewählt hast. Läuft dieses Modell lokal, bleibt der Seiteninhalt auf Hardware, die du selbst kontrollierst.

Ist das kostenlos? Ja. Eigene Endpunkte kosten in SurfMind nichts, und wir setzen keine Nutzungslimits. Du zahlst nur, was deine Anbieter verlangen – und bei lokalen Modellen ist das nichts.

Kommst du immer noch nicht weiter?

Wenn der curl-Test funktioniert, SurfMind aber trotzdem nicht mit deinen OpenWebUI-Modellen chatten will, schreib uns an wave@surfmind.ai. Gib deine API URL (ohne Schlüssel) an, den HTTP-Statuscode und ob nur bestimmte Modelle oder alle betroffen sind. Selbst gehostete Setups unterscheiden sich stark, und solche Rückmeldungen helfen uns, SurfMind reibungslos damit zum Laufen zu bringen.

SurfMind holen →