OpenWebUI API: chatea con cualquier web usando tus modelos

Si usas OpenWebUI, ya tienes hecho lo más difícil. Tus modelos están configurados y tus claves, centralizadas en un solo sitio: quizá Ollama en un servidor doméstico, uno o dos proveedores en la nube y algunos modelos de workspace personalizados que has ido afinando.

Lo que OpenWebUI no hace es funcionar dentro de las páginas que visitas. Para preguntarle a un modelo por el artículo, el PDF o la página de documentación que estás leyendo, sigues teniendo que copiar y pegar el contenido en otra pestaña.

Ahí es donde entra SurfMind. OpenWebUI no es solo una interfaz de chat. A través de la OpenWebUI API, también funciona como servidor de API, así que SurfMind puede usarlo como backend. Tú sigues gestionando los modelos en OpenWebUI, y SurfMind se convierte en su interfaz dentro del navegador.

Esta guía explica qué es la OpenWebUI API, cómo encaja con SurfMind, las URLs exactas que tienes que pegar y cómo resolver los errores con los que la gente se encuentra de verdad.

OpenWebUI y SurfMind: se parecen, pero cumplen funciones distintas

A primera vista parecen competidores. Los dos son interfaces de IA, los dos se conectan a muchos proveedores de LLM y los dos te permiten chatear con modelos. Pero están pensados para usos distintos:

OpenWebUI es un espacio de trabajo de IA autoalojado. SurfMind es IA dentro del navegador que ya usas. La fila que más importa es la que está en negrita. Como OpenWebUI puede servir tus modelos mediante una API, los dos se complementan.

¿Por qué conectar OpenWebUI a SurfMind?

Imagina una configuración típica. Tienes OpenWebUI en un servidor doméstico o en un VPS pequeño y, detrás:

• Llama, Qwen o Gemma ejecutándose en local con Ollama
• Modelos GPT o Claude a través de una API key en la nube
• Un modelo servido con vLLM en tu propia GPU
• Algunos modelos de workspace que creaste en OpenWebUI, cada uno con su propio prompt de sistema y su configuración

Todo eso está disponible desde la página de chat de OpenWebUI. Ahora además quieres lo que mejor hace un asistente de navegador: hacer preguntas sobre la página actual, resumir un hilo largo, comparar información entre pestañas o redactar una respuesta sin salir del sitio.

Podrías volver a añadir cada proveedor a SurfMind uno a uno: Ollama, luego tu clave de OpenAI, luego tu endpoint de vLLM. Es tedioso, duplica tus claves y los modelos de workspace que creaste se quedarían fuera.

O puedes añadir una sola conexión: SurfMind → OpenWebUI. Todos los modelos que ve OpenWebUI aparecen en el selector de modelos de SurfMind. Sigues gestionando modelos, usuarios y permisos en OpenWebUI, donde ya lo haces, y SurfMind añade la capa del navegador por encima.

También facilita que todo un equipo use la misma configuración. Si un equipo usa una única instancia de OpenWebUI, cada persona puede crear su propia API key y usar los modelos del equipo desde su navegador. Tendrá los mismos permisos que en OpenWebUI, y nadie necesita las claves de los proveedores.

Paso 1: crea una API key de OpenWebUI

Las API keys vienen desactivadas por defecto, así que la primera vez te llevará un minuto.

Si eres administrador, activa las API keys:

1. Inicia sesión en OpenWebUI como administrador.
2. Ve a Settings → Admin → Authentication.
3. Activa API Keys y haz clic en Save.

Si no eres administrador, pídele al tuyo que te dé el permiso de la función API Keys. Los administradores lo configuran en Admin Panel → Users → Groups, ya sea en Default Permissions para todo el mundo o en un grupo concreto.

Después, genera tu clave:

1. Haz clic en tu icono de perfil, abajo a la izquierda.
2. Abre Settings → Account.
3. En la sección API keys, haz clic en Show junto a Secrets. La sección aparece contraída por defecto, así que es normal que aquí parezca que no hay nada.
4. Haz clic en Create new secret key y cópiala. Empieza por sk-.

Algunas cosas que conviene saber, según la documentación de API keys de OpenWebUI:

• Una clave por cuenta. Al crear una clave nueva se sustituye la anterior, que deja de funcionar al instante. Si otra herramienta ya usa tu clave, crear una nueva para SurfMind la dejará sin acceso. Una cuenta dedicada sin permisos de administrador para SurfMind evita ese problema.
• La clave actúa en tu nombre. Ve los mismos modelos y tiene los mismos permisos que la cuenta que la creó.
• No uses el token JWT que se muestra a los administradores en el mismo panel. Es el token de tu sesión del navegador, y caduca.

Paso 2: añade OpenWebUI a SurfMind

En SurfMind, haz clic en el nombre del modelo en la parte inferior del panel y luego en Show all → Custom → Add Custom Models. Elige la configuración predefinida genérica OpenAI-compatible y rellena:

Si OpenWebUI se ejecuta en el mismo ordenador que tu navegador, el host suele ser http://localhost:3000 (la asignación de puertos habitual en Docker) o http://localhost:8080 (instalación con pip o directa en el sistema):

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

Guarda, elige uno de tus modelos de OpenWebUI en la lista, abre cualquier artículo y pídele a SurfMind que lo resuma.

Dos errores de ruta que debes evitar. Pega el endpoint completo terminado en /api/chat/completions, no solo el host ni /api. El campo API URL de SurfMind no añade la ruta por ti. Y no añadas /v1 en ningún sitio: ni /api/v1/chat/completions ni /v1/chat/completions son el endpoint de chat de OpenWebUI.

Resolución de problemas: "los modelos cargan, pero el chat falla"

Es el problema que más nos comunican los usuarios de OpenWebUI, así que tiene su propia sección. Si aparecen los modelos en el desplegable, tu host, tu clave y la ruta de red funcionan. Lo que falla es algo específico de la petición de chat. Revisa estos puntos en orden.

Primero, prueba fuera de SurfMind. Un curl rápido desde la terminal te dice si el problema está en OpenWebUI o en tu configuración de SurfMind. Sustituye el host, la clave y el id del modelo por los tuyos:

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 el id del modelo exactamente como aparece en la lista de modelos de SurfMind (o en GET /api/models). Si esto funciona, vuelve a revisar los campos de SurfMind. Si también falla, el error que devuelve te señala una de las causas siguientes.

1. La ruta del chat es incorrecta. La Models URL y la API URL son campos independientes, así que una puede estar bien y la otra mal. Comprueba que la API URL termina exactamente en /api/chat/completions, sin /v1, sin barra final y sin erratas.

2. Las restricciones de endpoints bloquean el chat. Los administradores pueden activar API Key Endpoint Restrictions, una lista de rutas permitidas a las que pueden llamar las API keys. Si incluye /api/models pero no /api/chat/completions, ocurre exactamente esto, normalmente como un 403. Pídele a tu administrador que añada /api/chat/completions.

3. Un ajuste del modelo fuerza un modo de streaming. OpenWebUI tiene un ajuste Stream Chat Response, que se configura por modelo en sus parámetros avanzados o como valor predeterminado de administrador en Settings → Admin → Models. Según la documentación de OpenWebUI, este ajuste decide si la respuesta se envía en streaming independientemente de lo que haya pedido el cliente. Si un modelo se ve forzado a un modo que el cliente no espera, la respuesta puede llegar en un formato que el cliente no sabe leer. Si el chat falla solo con ciertos modelos, revisa este ajuste en ellos y vuelve a ponerlo en Default.

4. Un proxy inverso se come la cabecera Authorization. Si OpenWebUI está detrás de una pasarela que usa Authorization para su propio inicio de sesión (autenticación básica, SSO, un API gateway), tu clave nunca llega a OpenWebUI. OpenWebUI también acepta la clave en una cabecera personalizada, x-api-key por defecto. En ese caso, elige x-api-key como API Key Header en SurfMind. Si tu administrador cambió el nombre de la cabecera con CUSTOM_API_KEY_HEADER, el proxy tiene que dejar pasar esa cabecera.

5. El id del modelo no coincide. Elige del desplegable en lugar de escribirlo. En OpenWebUI, los ids de los modelos de Ollama incluyen la etiqueta (llama3.2:latest), y los modelos de workspace usan el id que les diste, no su nombre visible.

6. Falla el proveedor que hay detrás de OpenWebUI. Cuando el proveedor de origen rechaza una petición, OpenWebUI reenvía su código de estado. Un 429 viene del límite de peticiones del proveedor, no de OpenWebUI ni de SurfMind. Prueba el mismo modelo en el chat de OpenWebUI. Si también falla ahí, el problema está en el proveedor.

Otros errores, de un vistazo

Para las reglas generales que se aplican a cualquier endpoint personalizado (puertos, http frente a https, URL base frente a endpoint completo), consulta nuestra guía para conectar una IA personalizada.

¿OpenWebUI, SurfMind o los dos?

No tienes que elegir.

• Solo OpenWebUI es ideal si la mayor parte de tu uso de la IA son conversaciones largas en una pestaña dedicada: chatear con documentos de tus bases de conocimiento, ejecutar pipelines o gestionar modelos para un equipo.
• Solo SurfMind es ideal si la mayor parte de tu uso de la IA parte de lo que tienes en pantalla y no te importa conectar directamente proveedores o un ejecutor local como Ollama.
• Usar los dos tiene sentido cuando ya has invertido en una configuración de OpenWebUI y quieres tenerla disponible en todas las páginas sin configurarlo todo dos veces.

El reparto es sencillo: OpenWebUI gestiona tus modelos y SurfMind los pone a trabajar en el navegador.

Preguntas frecuentes

¿OpenWebUI tiene API? Sí. La OpenWebUI API es una API REST que se autentica con tokens Bearer. Los dos endpoints que necesitan la mayoría de las herramientas son GET /api/models, para listar los modelos, y POST /api/chat/completions, para el chat, que acepta peticiones al estilo de OpenAI.

¿La OpenWebUI API es compatible con OpenAI? El formato de peticiones y respuestas, sí. Las rutas no son las estándar: OpenWebUI usa /api/chat/completions en lugar de /v1/chat/completions. Cualquier cliente que te permita indicar la URL completa del endpoint, como SurfMind, puede usarla.

¿Dónde encuentro mi API key de OpenWebUI? Ve a Settings → Account → API keys, haz clic en Show y luego en Create new secret key. Si no ves la sección, un administrador tiene que activar API Keys en Settings → Admin → Authentication y darle a tu cuenta el permiso de API Keys.

¿Puedo usar mis modelos de workspace de OpenWebUI en SurfMind? Sí. /api/models lista los modelos de workspace como cualquier otro modelo. Cuando los usas, OpenWebUI aplica la configuración que tengan guardada.

¿Conectar OpenWebUI envía mis datos a los servidores de SurfMind? Con un endpoint personalizado, SurfMind envía las peticiones a la URL que configuraste, en este caso tu servidor de OpenWebUI. Después, tu servidor de OpenWebUI las reenvía al modelo que hayas elegido. Si ese modelo se ejecuta en local, el contenido de la página se queda en hardware que controlas tú.

¿Es gratis? Sí. Los endpoints personalizados de SurfMind no cuestan nada y no les ponemos ningún límite de uso. Solo pagas lo que cobren tus propios proveedores, que en el caso de los modelos locales es nada.

¿Sigues atascado?

Si la prueba con curl funciona y SurfMind sigue sin poder chatear con tus modelos de OpenWebUI, escríbenos a wave@surfmind.ai. Incluye tu API URL (sin la clave), el código de estado HTTP y si fallan solo ciertos modelos o todos. Las configuraciones autoalojadas varían muchísimo, y estos avisos nos ayudan a que SurfMind funcione sin problemas con ellas.

Consigue SurfMind →