OpenWebUI API: converse com qualquer site com seus modelos

Se você usa o OpenWebUI, o trabalho pesado já está feito. Seus modelos estão configurados e suas chaves estão todas num lugar só, talvez com o Ollama num servidor em casa, um ou dois provedores de nuvem e alguns modelos de workspace personalizados que você mesmo ajustou.

O que o OpenWebUI não faz é funcionar dentro das páginas que você está navegando. Para perguntar a um modelo sobre o artigo, o PDF ou a documentação que você está lendo, você ainda precisa copiar o conteúdo e colar em outra aba.

É aí que entra o SurfMind. O OpenWebUI não é só uma interface de chat. Pela OpenWebUI API, ele também funciona como servidor de API, então o SurfMind pode usá-lo como backend. Você continua gerenciando os modelos no OpenWebUI, e o SurfMind vira o front-end deles dentro do navegador.

Este guia explica o que é a OpenWebUI API, como ela se relaciona com o SurfMind, quais URLs exatamente colar e como corrigir os erros que as pessoas realmente encontram.

OpenWebUI e SurfMind: parecidos por fora, funções diferentes

À primeira vista, os dois parecem concorrentes. Ambos são interfaces de IA, ambos se conectam a vários provedores de LLM e ambos permitem conversar com modelos. Só que cada um atende a necessidades diferentes:

O OpenWebUI é um workspace de IA auto-hospedado. O SurfMind é IA dentro do navegador que você já usa. A linha que mais importa é a que está em negrito. Como o OpenWebUI consegue servir seus modelos por uma API, os dois se encaixam.

Por que conectar o OpenWebUI ao SurfMind?

Imagine uma configuração típica. Você tem o OpenWebUI num servidor em casa ou numa VPS pequena e, por trás dele:

• Llama, Qwen ou Gemma rodando localmente pelo Ollama
• Modelos GPT ou Claude por uma chave de API de nuvem
• Um modelo servido pelo vLLM na sua própria GPU
• Alguns modelos de workspace que você criou no OpenWebUI, cada um com seu próprio system prompt e configurações

Tudo isso está acessível pela página de chat do OpenWebUI. Agora você também quer o que um assistente de navegador faz bem: tirar dúvidas sobre a página atual, resumir uma thread longa, comparar informações entre abas ou rascunhar uma resposta sem sair do site.

Você poderia adicionar cada provedor ao SurfMind de novo, um por um: o Ollama, depois sua chave da OpenAI, depois seu endpoint do vLLM. É trabalhoso, duplica suas chaves, e os modelos de workspace que você criou ficariam de fora.

Ou você adiciona uma conexão só: SurfMind → OpenWebUI. Todos os modelos que o OpenWebUI enxerga aparecem no seletor de modelos do SurfMind. Você continua gerenciando modelos, usuários e permissões no OpenWebUI, onde já faz isso, e o SurfMind acrescenta a camada do navegador por cima.

Também fica mais fácil compartilhar a mesma configuração com a equipe. Se uma equipe roda uma única instância do OpenWebUI, cada pessoa pode criar a própria chave de API e usar os modelos da equipe direto do navegador. Cada um fica com as mesmas permissões que já tem no OpenWebUI, e ninguém precisa ter acesso às chaves dos provedores.

Passo 1: crie uma chave da OpenWebUI API

As chaves de API vêm desativadas por padrão, então da primeira vez isso leva um minuto.

Se você é o administrador, ative as chaves de API:

1. Entre no OpenWebUI como administrador.
2. Vá em Settings → Admin → Authentication.
3. Ative API Keys e clique em Save.

Se você não é administrador, peça ao seu admin a permissão de recurso API Keys. Os admins configuram isso em Admin Panel → Users → Groups, seja em Default Permissions para todo mundo, seja em um grupo específico.

Depois, gere sua chave:

1. Clique no seu ícone de perfil no canto inferior esquerdo.
2. Abra Settings → Account.
3. Na seção API keys, clique em Show ao lado de Secrets. A seção vem recolhida por padrão, então é normal ela parecer vazia.
4. Clique em Create new secret key e copie a chave. Ela começa com sk-.

Algumas coisas que vale saber, segundo a documentação de chaves de API do OpenWebUI:

• Uma chave por conta. Criar uma chave nova substitui a antiga, e a antiga para de funcionar na hora. Se outra ferramenta já usa sua chave, gerar uma nova para o SurfMind vai quebrar essa ferramenta. Uma conta dedicada, sem privilégios de admin, só para o SurfMind evita esse problema.
• A chave age em seu nome. Ela vê os mesmos modelos e tem as mesmas permissões da conta que a criou.
• Não use o token JWT que aparece para admins no mesmo painel. Esse é o token da sua sessão no navegador, e ele expira.

Passo 2: adicione o OpenWebUI ao SurfMind

No SurfMind, clique no nome do modelo na parte inferior do painel e depois em Show all → Custom → Add Custom Models. Escolha a configuração predefinida genérica OpenAI-compatible e preencha:

Se o OpenWebUI roda no mesmo computador que o seu navegador, o host geralmente é http://localhost:3000 (o mapeamento de porta mais comum no Docker) ou http://localhost:8080 (instalação via pip ou direto no sistema):

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

Salve, escolha um dos seus modelos do OpenWebUI na lista, abra qualquer artigo e peça ao SurfMind para resumi-lo.

Dois erros de caminho para evitar. Cole o endpoint completo, terminando em /api/chat/completions, e não só o host ou /api. O campo API URL do SurfMind não completa o caminho para você. E não coloque /v1 em lugar nenhum. /api/v1/chat/completions e /v1/chat/completions não são o endpoint de chat do OpenWebUI.

Solução de problemas: "os modelos carregam, mas o chat falha"

Esse é o problema mais relatado com o OpenWebUI, por isso ganhou uma seção só para ele. Se os modelos aparecem no menu de seleção, seu host, sua chave e o caminho de rede estão funcionando. O que está falhando é algo específico da requisição de chat. Verifique os itens abaixo, nesta ordem.

Primeiro, teste fora do SurfMind. Um curl rápido no terminal mostra se o problema está no OpenWebUI ou nas configurações do SurfMind. Troque o host, a chave e o id do modelo pelos seus:

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

Use o id do modelo exatamente como ele aparece na lista de modelos do SurfMind (ou em GET /api/models). Se funcionar, revise os campos no SurfMind. Se também falhar, o erro retornado aponta para uma das causas abaixo.

1. O caminho do chat está errado. Models URL e API URL são campos separados, então um pode estar certo e o outro errado. Confira se o API URL termina exatamente em /api/chat/completions, sem /v1, sem barra no final e sem erro de digitação.

2. Restrições de endpoint bloqueiam o chat. Os admins podem ativar API Key Endpoint Restrictions, uma lista de rotas permitidas que as chaves de API podem chamar. Se ela inclui /api/models mas não /api/chat/completions, acontece exatamente isso, normalmente como um 403. Peça ao seu admin para adicionar /api/chat/completions.

3. Uma configuração do modelo força um modo de streaming. O OpenWebUI tem a opção Stream Chat Response, definida por modelo nos parâmetros avançados ou como padrão do admin em Settings → Admin → Models. Segundo a documentação do OpenWebUI, essa opção decide se a resposta é enviada em streaming independentemente do que o cliente pediu. Se um modelo for forçado a um modo que o cliente não espera, a resposta pode voltar num formato que o cliente não consegue ler. Se o chat falha só com alguns modelos, confira essa opção neles e volte para Default.

4. Um proxy reverso engole o cabeçalho Authorization. Se o OpenWebUI fica atrás de um gateway que usa Authorization para o próprio login (basic auth, SSO, um API gateway), sua chave nunca chega ao OpenWebUI. O OpenWebUI também aceita a chave num cabeçalho personalizado, x-api-key por padrão. Nesse caso, escolha x-api-key como API Key Header no SurfMind. Se o seu admin renomeou o cabeçalho com CUSTOM_API_KEY_HEADER, o proxy precisa deixar esse cabeçalho passar.

5. O id do modelo não bate. Escolha no dropdown em vez de digitar. Os ids do OpenWebUI para modelos do Ollama incluem a tag (llama3.2:latest), e os modelos de workspace usam o id que você deu a eles, não o nome de exibição.

6. O provedor por trás do OpenWebUI está falhando. Quando o provedor upstream rejeita uma requisição, o OpenWebUI repassa o código de status dele. Um 429 vem do limite de requisições do provedor, não do OpenWebUI nem do SurfMind. Teste o mesmo modelo no chat do próprio OpenWebUI. Se falhar lá também, o problema está no provedor.

Outros erros, em resumo

Para as regras gerais que valem para qualquer endpoint personalizado (portas, http vs https, URL base vs endpoint completo), veja nosso guia de conexão de IA personalizada.

OpenWebUI, SurfMind ou os dois?

Não é uma coisa ou outra.

• Só o OpenWebUI é ótimo se a maior parte do seu uso de IA são conversas longas numa aba dedicada: conversar com documentos das suas bases de conhecimento, rodar pipelines, gerenciar modelos para uma equipe.
• Só o SurfMind é ótimo se a maior parte do seu uso de IA começa no que está na sua tela e você não se importa de conectar provedores ou um runner local como o Ollama diretamente.
• Usar os dois faz sentido quando você já investiu numa configuração do OpenWebUI e quer tê-la disponível em toda página sem configurar tudo duas vezes.

A divisão é simples: o OpenWebUI gerencia seus modelos, e o SurfMind os coloca para trabalhar no navegador.

Perguntas frequentes

O OpenWebUI tem API? Sim. A OpenWebUI API é uma API REST autenticada com tokens Bearer. Os dois endpoints de que a maioria das ferramentas precisa são GET /api/models, para listar os modelos, e POST /api/chat/completions, para o chat, que aceita requisições no formato da OpenAI.

A OpenWebUI API é compatível com a OpenAI? O formato de requisição e resposta é. Os caminhos é que são diferentes dos convencionais: o OpenWebUI usa /api/chat/completions em vez de /v1/chat/completions. Qualquer cliente que deixe você definir a URL completa do endpoint, como o SurfMind, consegue usá-la.

Onde encontro minha chave de API do OpenWebUI? Vá em Settings → Account → API keys, clique em Show e depois em Create new secret key. Se a seção não aparecer, um admin precisa ativar API Keys em Settings → Admin → Authentication e dar à sua conta a permissão API Keys.

Posso usar meus modelos de workspace do OpenWebUI no SurfMind? Sim. Os modelos de workspace aparecem em /api/models como qualquer outro modelo. Quando você os chama, o OpenWebUI aplica as configurações salvas deles.

Conectar o OpenWebUI envia meus dados para os servidores do SurfMind? Com um endpoint personalizado, o SurfMind envia as requisições para a URL que você configurou, que aqui é o seu servidor do OpenWebUI. O seu servidor do OpenWebUI então as repassa para o modelo que você escolheu. Se esse modelo roda localmente, o conteúdo da página fica em hardware que você controla.

É grátis? Sim. Endpoints personalizados no SurfMind não custam nada e não têm limite de uso da nossa parte. Você paga só o que os seus próprios provedores cobram, e para modelos locais isso é zero.

Ainda com problemas?

Se o teste com curl funciona e o SurfMind ainda não conversa com seus modelos do OpenWebUI, mande um e-mail para wave@surfmind.ai. Inclua seu API URL (sem a chave), o código de status HTTP e se a falha acontece com alguns modelos ou com todos. Configurações auto-hospedadas variam muito, e esses relatos nos ajudam a fazer o SurfMind funcionar bem com elas.

Obter o SurfMind →