A configuração da URL base da API OpenAI do Open WebUI é o pequeno campo que decide se o Open WebUI envia o tráfego de chat para um provedor upstream, um servidor de modelo local ou um roteador como o Flatkey. Para uma implantação em equipe, esse campo não deve ser tratado como um detalhe de copiar e colar. Ele deve ser verificado com a chave de API, os IDs dos modelos, o comportamento de descoberta de modelos, as conclusões de chat, o streaming e os registros de uso.
Este guia foi escrito para desenvolvedores, equipes de produtos de IA, criadores de automação, engenheiros de plataforma, operadores financeiros e revisores de aquisições que desejam que o Open WebUI use o Flatkey como um roteador de modelos compatível com OpenAI. Ele mostra o caminho de conexão atual do Open WebUI, a URL base do Flatkey a ser verificada, quando usar filtros de modelo, como executar uma verificação prévia com curl e o que registrar antes de distribuir a configuração para mais usuários.
Nota da fonte: isto foi verificado em 29 de junho de 2026 com base na documentação oficial de compatibilidade com OpenAI do Open WebUI, na página inicial do Flatkey ao vivo e na página de preços do Flatkey ao vivo. Nenhuma chave de API do Flatkey ou instância do Open WebUI ao vivo estava disponível neste tempo de execução, portanto, os comandos abaixo são modelos para serem executados com sua própria chave, alias de modelo e implantação do Open WebUI.
Resposta rápida: URL base da API OpenAI do Open WebUI para o Flatkey
Para uma rota do Flatkey, defina a URL base da API OpenAI do Open WebUI para a URL base do provedor Flatkey atual da sua conta. A página inicial pública do Flatkey verificada para este artigo diz para apontar clientes compatíveis com OpenAI para https://console.flatkey.ai/v1. No Open WebUI, use essa URL base, cole uma chave de API do Flatkey, adicione os IDs exatos do modelo Flatkey se a descoberta de modelos for ruidosa ou falhar e, em seguida, salve a conexão.
| Campo do Open WebUI | Valor do Flatkey | Verificação de revisão |
|---|---|---|
| URL | https://console.flatkey.ai/v1, a menos que sua conta Flatkey mostre uma URL base de provedor mais recente |
Use apenas a URL base. Não cole /chat/completions no campo da URL. |
| Chave de API | Uma chave Flatkey pertencente ao espaço de trabalho, equipe ou ambiente correto | Use primeiro uma chave de teste com escopo definido e, em seguida, rotacione ou separe as chaves para usuários de produção. |
| IDs de Modelo (Filtro) | Aliases de modelo exatos do Flatkey aprovados para o Open WebUI | Adicione-os manualmente quando a verificação de /models falhar, retornar muitos modelos ou expor modelos que você não deseja que os usuários selecionem. |
| Alternador de conexão | Habilitado somente após uma verificação prévia de chat bem-sucedida | Mantenha o provedor anterior disponível até que a rota do Flatkey seja comprovada. |
A versão curta é: configure a URL, a chave e o filtro de modelo, depois teste uma solicitação de chat e confirme se a solicitação aparece no uso do Flatkey. O restante deste guia da URL base da API OpenAI do Open WebUI transforma isso em uma lista de verificação repetível de configuração e solução de problemas.
O que os documentos atuais do Open WebUI confirmam
O guia oficial de compatibilidade com OpenAI do Open WebUI diz que o Open WebUI pode se conectar a qualquer servidor ou provedor que implemente a API compatível com OpenAI. Os documentos enquadram a integração em torno de protocolos padrão, especialmente o protocolo OpenAI Chat Completions, em vez de um módulo personalizado para cada provedor. Isso torna o Flatkey uma tarefa de configuração de URL base, chave e seleção de modelo.
O mesmo guia fornece o caminho de administração atual: abra o Open WebUI, vá para Configurações de Administrador, depois Conexões, depois OpenAI e clique em Adicionar Conexão. A partir daí, preencha a URL do provedor e a chave de API. Se a descoberta automática de modelos não funcionar, adicione os IDs dos modelos em IDs de Modelo (Filtro) e salve.
Um aviso do Open WebUI é especialmente importante para configurações de roteador. Quando uma conexão é adicionada, o Open WebUI a verifica através do endpoint /models do provedor com um token de portador padrão. Os documentos dizem que alguns provedores não implementam /models, usam comportamento não padrão ou retornam uma lista de modelos difícil de gerenciar. Um erro na lista de modelos não significa automaticamente que as conclusões de chat são incompatíveis. Significa que você pode precisar adicionar os IDs dos modelos manualmente e testar o endpoint de chat diretamente.
Para compatibilidade total, o Open WebUI lista /v1/models como recomendado e /v1/chat/completions como o endpoint de chat principal necessário. Ele também passa parâmetros comuns do OpenAI, como temperature, top_p, max_tokens ou max_completion_tokens, stop, seed e logit_bias. O uso de ferramentas é suportado quando o modelo e o servidor suportam tools e tool_choice.
Valores do Flatkey a serem verificados antes de alterar o Open WebUI
A página inicial do Flatkey verificada em 29 de junho de 2026 tem o título One API gateway for production AI teams e descreve acesso unificado a modelos, roteamento, faturamento, análise de uso e controles operacionais. Ela também diz que as equipes devem apontar um cliente compatível com OpenAI para https://console.flatkey.ai/v1 e manter o padrão de SDK ou cliente existente.
A página de preços do Flatkey, verificada no mesmo dia, informa que o catálogo público tem 633 modelos habilitados em 23 provedores. Ela também expõe famílias de endpoints, incluindo /v1/chat/completions, /v1/responses, /v1/messages, /v1/images/generations e /v1/video/generations. Para o chat do Open WebUI, comece com um modelo que esteja disponível através do caminho de conclusões de chat e aprovado para a chave que você planeja usar.
Não presuma que todo modelo do catálogo é um bom modelo para o Open WebUI. A URL base da API OpenAI do Open WebUI aponta para um roteador, mas a experiência do usuário depende do alias do modelo escolhido, do suporte ao endpoint, da latência, do comportamento do contexto, do suporte a ferramentas e se o modelo aparece de forma limpa no seletor de modelos do Open WebUI.
Passo a passo: adicione o Flatkey como a conexão OpenAI
- Escolha o escopo do Open WebUI. Decida se esta é uma conexão para toda a administração, uma instância de teste ou uma implantação auto-hospedada gerenciada por meio de variáveis de ambiente.
- Crie ou selecione uma chave Flatkey. Use uma chave dedicada para o teste do Open WebUI para que o uso possa ser atribuído e limitado.
- Escolha um modelo inicial. Copie o alias exato do modelo da página de preços do Flatkey, do console do Flatkey ou da sua lista de modelos visíveis na conta.
- Abra a tela de conexão. No Open WebUI, vá para Configurações de Administrador > Conexões > OpenAI > Adicionar Conexão.
- Cole a URL do Flatkey. Use
https://console.flatkey.ai/v1se sua conta confirmar. O valor deve incluir/v1, mas não/chat/completions. - Cole a chave Flatkey. Use a chave criada para esta implantação do Open WebUI, não uma chave de provedor pessoal ou uma chave de provedor upstream não relacionada.
- Adicione IDs de modelo quando necessário. Se a descoberta de modelos falhar, retornar muitas opções ou expor modelos fora da política, adicione os aliases exatos aprovados em IDs de Modelo (Filtro).
- Salve e mantenha a rota anterior por perto. O Open WebUI permite que as conexões sejam habilitadas ou desabilitadas, então preserve uma rota de reversão durante os testes.
- Execute um prompt de baixo risco. Use um prompt simples no Open WebUI e, em seguida, confirme a solicitação no uso do Flatkey por carimbo de data/hora, chave, modelo, contagem de tokens e custo.
- Documente o proprietário. Registre quem é o proprietário da chave, quem pode rotacioná-la, quais modelos são aprovados e qual cota se aplica antes de expandir o acesso.
Modelo opcional de variável de ambiente
Se sua implantação for gerenciada por meio de variáveis de ambiente, use os nomes suportados pela sua versão e método de implantação do Open WebUI. Os exemplos de provedor do Open WebUI mostram os padrões OPENAI_API_BASE_URL e OPENAI_API_KEY para back-ends compatíveis com OpenAI, mas o painel de administração também pode gerenciar conexões. Trate isso como um modelo de implantação para verificar em relação à sua versão.
OPENAI_API_BASE_URL=https://console.flatkey.ai/v1
OPENAI_API_KEY=fk_replace_with_flatkey_key
Se você também rotear embeddings, geração de imagens, fala ou outros recursos no estilo OpenAI através do Open WebUI, configure essas variáveis de URL base e chave específicas do recurso somente após confirmar que o Flatkey e o modelo selecionado suportam essa família de endpoints. Para o primeiro lançamento da URL base da API OpenAI do Open WebUI, mantenha o teste focado nas conclusões de chat.
Verifique previamente a rota do Flatkey antes de culpar o Open WebUI
Uma verificação prévia com curl separa problemas de roteador e credenciais de problemas da interface do usuário do Open WebUI. Execute isso de um local de rede comparável ao servidor Open WebUI.
export FLATKEY_API_KEY="fk_replace_me"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1"
export FLATKEY_OPEN_WEBUI_MODEL="replace-with-flatkey-model-alias"
curl "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_OPEN_WEBUI_MODEL"'",
"messages": [
{
"role": "user",
"content": "Return the word ok."
}
],
"stream": false,
"max_tokens": 16
}'Se essa solicitação falhar, corrija a chave, URL, alias do modelo, permissão da conta ou rota de rede do Flatkey antes de alterar o Open WebUI novamente. Se for bem-sucedida, repita através do Open WebUI e compare o registro de uso do Flatkey.
Para uma experiência de chat com streaming, teste o streaming separadamente. Uma resposta sem streaming prova que a rota pode responder. Isso não prova que seu proxy reverso, implantação do Open WebUI e navegador do cliente lidam com streaming sem buffer ou timeouts.
curl "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_OPEN_WEBUI_MODEL"'",
"messages": [
{
"role": "user",
"content": "Stream three short bullet points."
}
],
"stream": true,
"max_tokens": 96
}'Checklist de descoberta e filtro de modelos
A configuração mais segura da URL base da API OpenAI do Open WebUI usa filtros de modelo intencionalmente. Um roteador pode expor muitos modelos, e uma lista ampla de modelos nem sempre é o que os administradores querem que os usuários vejam.
| Decisão | O que verificar | Por que é importante |
|---|---|---|
| Alias do modelo | ID exato do modelo Flatkey visível para a chave | O Open WebUI envia a string do modelo conforme configurado. Um nome de exibição não é suficiente. |
Descoberta de /models |
Comportamento ao salvar a conexão e saída do seletor de modelo | O Open WebUI pode mostrar um erro de verificação mesmo quando as conclusões de chat funcionam através de uma lista de permissões manual. |
| Conclusões de chat | /v1/chat/completions retorna uma resposta normal |
Este é o caminho de chat do Open WebUI necessário na tabela de compatibilidade oficial. |
| Streaming | O navegador recebe saída incremental sem buffer longo | O streaming pode falhar devido ao comportamento do proxy ou do tempo de execução, mesmo quando o chat sem streaming funciona. |
| Ferramentas | O modelo e a rota suportam tools e tool_choice quando necessário |
O Open WebUI só pode passar parâmetros de ferramenta se o backend selecionado os suportar. |
| Visibilidade de uso | O Flatkey mostra carimbo de data/hora, chave, modelo, tokens, status e custo | As equipes de plataforma e finanças precisam de prova de que a nova rota é atribuível. |
Modos de falha para depurar primeiro
| Sintoma | Causa provável | Correção |
|---|---|---|
| Salvar a conexão mostra um erro na lista de modelos | A descoberta de /models falhou, retornou muitos modelos ou não correspondeu às expectativas do Open WebUI |
Adicione os IDs exatos do modelo a IDs de Modelo (Filtro), salve novamente e teste as conclusões de chat. |
| 401 ou chave inválida | A chave não é uma chave Flatkey, foi copiada incorretamente, foi rotacionada ou pertence ao workspace errado | Gere uma chave Flatkey dedicada e teste novamente com curl antes de atualizar a interface do usuário. |
| 404 ou rota não encontrada | A URL inclui o endpoint completo ou omite o caminho base necessário | Use https://console.flatkey.ai/v1 como a URL base quando sua conta confirmar. |
| Modelo não encontrado | O valor do modelo do Open WebUI não corresponde a um alias do Flatkey habilitado | Copie o alias exato do modelo do Flatkey e adicione-o ao filtro de modelos. |
| O chat funciona, mas o streaming parece travado | Buffer de proxy reverso, tempo limite do servidor ou problema no caminho do navegador/rede | Teste o streaming com curl e, em seguida, inspecione as configurações de tempo limite do servidor e do proxy do Open WebUI. |
| Os gastos não podem ser reconciliados | Chave compartilhada, proprietário do modelo incerto ou nenhum registro de implementação | Use uma chave Flatkey dedicada e registre o proprietário, o ambiente, os IDs do modelo e a cota antes de expandir o acesso. |
Runbook de produção para Open WebUI e Flatkey
Antes de fazer a alteração da URL base da API OpenAI do Open WebUI para um grupo maior, anote os fatos operacionais que dão suporte à propriedade, reversão e revisão de custos.
| Campo do runbook | Registre isto |
|---|---|
| Implantação do Open WebUI | URL, versão se conhecida, proprietário e se as conexões são gerenciadas pelo administrador ou pelo ambiente. |
| URL base do Flatkey | URL base atual aprovada pela conta e data da verificação. |
| Proprietário da chave Flatkey | Equipe, ambiente, proprietário da rotação, cota e proprietário do alerta. |
| Lista de permissões de modelos | Aliases exatos de modelos expostos aos usuários do Open WebUI e o motivo pelo qual cada um foi aprovado. |
| Prova do endpoint | Verificações de chat sem streaming, chat com streaming e uso de ferramentas, quando relevante. |
| Prova de uso | Linhas de uso do Flatkey mostrando a chave esperada, carimbo de data/hora, modelo, tokens, status da solicitação e custo. |
| Reversão | Conexão anterior, plano de desativação, caminho de revogação da chave e aprovação do proprietário. |
Onde isso se encaixa no cluster de integração de ferramentas do Flatkey
O Open WebUI é apenas uma das superfícies que pode usar uma rota compatível com OpenAI. Se sua equipe está padronizando várias ferramentas, use o mesmo padrão em todo o cluster: uma URL base atual, uma chave de propriedade da conta por superfície, aliases de modelo exatos, um pequeno teste de fumaça, prova de uso e notas de reversão.
Para configurações adjacentes, consulte o guia de configuração da API do Cherry Studio para disciplina de URL base de cliente de desktop, o guia CC Switch Claude Code Flatkey para roteamento de ferramentas de desenvolvedor e o manual mais amplo de migração de API compatível com OpenAI para alterações de URL base, verificação de alias de modelo e reversão. Use os preços do Flatkey para revisar a cobertura atual de modelos e endpoints e, em seguida, obtenha uma chave para o workspace que possui a primeira implementação do Open WebUI.
FAQ
O que devo colocar no campo de URL base da API OpenAI do Open WebUI?
Use a URL base atual do provedor Flatkey da sua conta. A página inicial pública do Flatkey, verificada em 29 de junho de 2026, direciona os clientes compatíveis com OpenAI para https://console.flatkey.ai/v1. Não inclua o caminho completo /chat/completions no campo da URL base.
Por que o Open WebUI mostra um erro de descoberta de modelo?
O Open WebUI verifica uma nova conexão compatível com OpenAI chamando /models. A documentação oficial alerta que alguns provedores não implementam esse endpoint, usam comportamento não padrão ou retornam listas de modelos muito grandes. Se as conclusões de chat funcionarem, adicione os IDs exatos dos modelos ao filtro e teste novamente.
Posso expor todos os modelos do Flatkey para o Open WebUI?
Tecnicamente, um roteador pode expor muitos modelos, mas os administradores de produção devem começar com uma lista de permissões restrita. Escolha modelos que correspondam às necessidades de chat do Open WebUI, suporte de endpoint, expectativas de latência, política de uso e controles de orçamento.
O Flatkey substitui as configurações do Open WebUI?
Não. O Flatkey fornece a rota compatível com OpenAI, chave, acesso ao modelo, visibilidade de uso e controles de faturamento. O Open WebUI ainda controla suas próprias configurações de conexão, seletor de modelo, acesso do usuário, comportamento do prompt e rede em nível de implantação.
Como sei que a configuração está funcionando?
Execute um preflight com curl para /chat/completions, salve a conexão do Open WebUI, envie um prompt seguro e confirme se a solicitação aparece no uso do Flatkey com a chave, modelo, carimbo de data/hora, tokens, status e custo esperados.
Lista de verificação final
- URL base do Flatkey confirmada a partir da origem da conta atual.
- Chave dedicada do Flatkey criada para a implantação do Open WebUI.
- Um alias de modelo de chat aprovado selecionado primeiro.
- URL base da API OpenAI do Open WebUI definida como a URL base do provedor, não o endpoint completo.
- IDs de modelo adicionados manualmente quando a descoberta falha ou retorna muitas opções.
- Chat com e sem streaming testado.
- Linha de uso do Flatkey confirmada após o primeiro prompt do Open WebUI.
- Proprietário, cota, lista de permissões de modelos e caminho de reversão registrados.
Assim que essas verificações forem aprovadas, a URL base da API OpenAI do Open WebUI se torna mais do que um campo de conexão. Ela se torna uma rota controlada do Flatkey com uma chave, modelos aprovados, visibilidade de uso e um plano de reversão claro.
