Endpoints personalizados e Base URL

Endpoint de API personalizado: como conectar uma API compatível com OpenAI

O que são endpoint de API personalizado e Base URL, e como conectar uma API compatível com OpenAI, relay, proxy ou gateway só com um endereço e uma chave.

Atualizado em
  • Um endpoint de API personalizado é o endereço da web, ou Base URL (URL base), de um serviço de IA que não vem integrado ao seu app, como uma API compatível com OpenAI, um relay (retransmissão), um proxy ou um gateway. No Oriveo, para conectar um deles você normalmente precisa de duas coisas: esse endereço e uma API key (chave de API).
  • O Oriveo descobre o protocolo para você (OpenAI Chat Completions, OpenAI Responses, Anthropic Messages ou Gemini) e acrescenta o caminho de versão, como /v1, quando você digita só o endereço raiz.
  • Endereços públicos precisam usar HTTPS. Um serviço de terceiros consegue ver tudo o que você envia por ele, então use uma chave separada com limite de gasto e nunca entregue a ele a chave do seu provedor oficial.
Oriveo no iPhone: a tela de provedores, com os provedores que você conectou e o gasto deste mês.

O que é Base URL ou endpoint de API?

Todo serviço de IA tem um endereço da web para onde os apps enviam as solicitações. Os desenvolvedores chamam isso de Base URL, endpoint da API ou URL de solicitação; aqui, tudo quer dizer a mesma coisa. Parece um endereço comum da web. O da OpenAI, por exemplo, é https://api.openai.com/v1.

No Oriveo, os 15 provedores integrados já vêm com o endereço preenchido, então basta colar a chave. O endpoint personalizado serve para todo o resto: um serviço que oferece uma API compatível com OpenAI, um relay ou gateway mantido por uma empresa, ou um gateway que você roda no seu próprio servidor.

"Compatível com OpenAI" quer dizer que o serviço aceita solicitações no mesmo formato da API da OpenAI, então apps feitos para a OpenAI conseguem conversar com ele. Muitos provedores e gateways oferecem esse formato.

Relay, proxy, gateway: qual a diferença?

Essas palavras são usadas meio sem rigor e, para conectar um app, todas funcionam do mesmo jeito: um serviço fica entre o seu app e os provedores de modelos, recebe a sua solicitação e a repassa. Alguns reúnem vários provedores com uma chave e uma cobrança só; outros acrescentam controles de uso para uma equipe; outros são programas que você roda no seu próprio servidor.

O Oriveo não recomenda nem classifica nenhum deles. Seja qual for o que você usa, os passos abaixo são os mesmos.

Do que preciso para conectar um endpoint personalizado?

Normalmente, de duas coisas, que você encontra no painel ou na documentação do próprio serviço:

  • A URL de solicitação (Base URL), por exemplo https://api.example.com/v1. Ela precisa começar com https:// se o serviço estiver na internet pública.
  • Uma API key emitida pelo serviço para você. Dá para adicionar mais chaves com "Adicionar outra chave".
  • Opcional: um nome para a conexão, para diferenciá-la das outras.

Como adiciono um endpoint personalizado no Oriveo?

Os passos são os mesmos no iPhone, no Android e na web.

  • Abra Provedores e toque no botão + (Adicionar provedor).
  • Escolha o filtro Personalizado e depois Retransmissão personalizada ("Conecte seu próprio serviço de modelos").
  • Em "Conecte uma retransmissão personalizada", cole a URL de solicitação e a API key. A linha "Será enviado para …" mostra o endereço completo que o Oriveo vai usar. Toque em Próximo.
  • O Oriveo testa a conexão, lê a lista de modelos e descobre o protocolo de cada modelo. Essa etapa só lê a lista, sem enviar nenhuma mensagem de chat.
  • Marque os modelos que quiser e toque em "Salvar (selecionados: N)". Se o serviço não listar os modelos, use "Adicionar ID de modelo manualmente".
  • Antes de salvar, o Oriveo envia uma solicitação bem pequena ao primeiro modelo selecionado. A conexão é salva quando esse teste passa; se ele falhar, você continua na mesma etapa e pode corrigir.
Tela Provedores do Oriveo no iPhone, com o botão + no canto superior direito e a lista de provedores conectados
Toque em + na tela Provedores e escolha Personalizado para adicionar um endpoint ao lado dos provedores integrados.

Prefere configurar tudo por conta própria? Use a Configuração manual

A Configuração manual coloca tudo em uma página só: o endereço, a chave, um ID de modelo, um nome opcional para a conexão e o protocolo padrão, que começa no automático. Toque em "Validar e salvar". Se a verificação falhar, nada é salvo ainda, e o cartão de falha oferece "Salvar mesmo assim (não verificado)", caso você queira manter a conexão e testar depois.

O Oriveo detecta o protocolo automaticamente?

Na maioria dos casos, sim. Os serviços de IA usam um entre poucos formatos de solicitação, chamados protocolos. O Oriveo aceita quatro: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages e Gemini generateContent.

Ele decide modelo por modelo. Usa o que o serviço informa sobre cada modelo, quando essa informação existe, e, se não existir, escolhe os candidatos mais prováveis pela família do modelo. Na hora de salvar, o primeiro modelo selecionado é testado com uma solicitação real; os outros são verificados depois, quando você começa a usá-los.

Por isso, na maioria dos casos o endereço e a chave bastam. Se a documentação do serviço indicar um protocolo específico, ou se um modelo falhar na verificação, escolha o protocolo você mesmo na Configuração manual.

Preciso colocar /v1 no endereço?

Geralmente não. Se você digitar só o endereço raiz, como https://api.example.com, o Oriveo acrescenta o caminho de versão padrão do protocolo: /v1 para os formatos da OpenAI e da Anthropic, /v1beta para o Gemini.

Se o endereço já tiver uma versão, como /api/paas/v4, o Oriveo mantém. Se você colar um endpoint completo terminado em /chat/completions, /responses, /messages ou :generateContent, o Oriveo tira esse final e usa essa informação para saber qual protocolo o serviço usa.

Confira a linha "Será enviado para …" antes de tocar em Próximo. Se a verificação disser "O endereço pode estar apontando para uma página da web. Verifique se falta /v1.", compare o seu endereço com a documentação do serviço.

Preciso colocar /v1 no endereço?
Você digitaO Oriveo solicita (formato OpenAI)
https://api.example.comhttps://api.example.com/v1
https://api.example.com/v1https://api.example.com/v1
https://api.example.com/v1/chat/completionshttps://api.example.com/v1, usando Chat Completions
https://api.example.com/api/paas/v4https://api.example.com/api/paas/v4

Quais endereços são aceitos?

O Oriveo segue algumas regras para proteger a sua chave:

  • Endereços públicos precisam começar com https://. Um endereço http:// na internet pública não pode ser testado nem salvo.
  • Endereços com usuário e senha embutidos, ou com parâmetros de consulta (qualquer coisa depois de um "?"), não são aceitos. O Oriveo nunca tenta usar API keys que estejam em parâmetros de consulta.
  • Endereços http:// simples na sua rede doméstica ou em uma VPN privada, como um servidor de modelos no seu próprio computador, vão pela entrada separada "Computação local" (no iPhone, "Computação local e LAN"), e não pela Retransmissão personalizada.
  • No iPhone e no Android, o app se conecta diretamente ao endereço.
  • No app web, as URLs de solicitação públicas são encaminhadas pelo servidor do Oriveo para contornar as limitações de CORS do navegador (uma regra de segurança do navegador que bloqueia muitas solicitações diretas). Sua chave de API fica apenas na memória durante essa requisição e nunca é armazenada nem registrada. Endereços da rede local se conectam diretamente do seu dispositivo, e o HTTPS é obrigatório nos dois casos; um endereço http:// simples na sua rede doméstica precisa do app para iPhone ou Android e da entrada Computação local (no iPhone, Computação local e LAN).
  • As chaves ficam neste dispositivo e não são enviadas pela sincronização na nuvem.

Base URLs dos provedores integrados

No Oriveo você não precisa delas: basta escolher o provedor pelo nome. Elas estão aqui porque muita gente procura esses endereços para usar em outras ferramentas. Cada uma é o endereço oficial compatível com OpenAI informado na documentação do provedor, em 18 de novembro de 2026.

  • A Anthropic descreve a camada compatível com OpenAI dela como feita para testes e comparação, e o guia de início rápido da Mistral não descreve a API dela como compatível com OpenAI. Adicione as duas como provedores integrados.
Base URLs dos provedores integrados
ProvedorBase URL compatível com OpenAI
OpenAIhttps://api.openai.com/v1
Google Geminihttps://generativelanguage.googleapis.com/v1beta/openai/
OpenRouterhttps://openrouter.ai/api/v1
DeepSeekhttps://api.deepseek.com
xAI (Grok)https://api.x.ai/v1
Groqhttps://api.groq.com/openai/v1
Together AIhttps://api.together.ai/v1
Fireworks AIhttps://api.fireworks.ai/inference/v1
MiniMax (internacional)https://api.minimax.io/v1
Z.ai (internacional)https://api.z.ai/api/paas/v4/
Qwen (região de Singapura)https://dashscope-intl.aliyuncs.com/compatible-mode/v1
Kimi (internacional)https://api.moonshot.ai/v1
SiliconFlow (internacional)https://api.siliconflow.com/v1

É seguro usar um relay ou uma API de terceiros?

Tome cuidado. Qualquer serviço entre você e o modelo pode ler os seus prompts, os arquivos que você anexa e as respostas, e ele define os próprios preços. O Oriveo não consegue ver o que acontece lá dentro nem dar garantias sobre ele.

  • Nunca entregue a um serviço de terceiros a API key da sua conta no provedor oficial. Use a chave que o serviço emitiu para você.
  • Crie uma chave separada para o Oriveo e, se o serviço permitir, defina um limite de gasto ou mantenha um saldo pequeno nela.
  • Não envie senhas, números de documentos nem trabalho confidencial por um serviço em que você não confia.
  • Acompanhe o uso no painel do próprio serviço. Os valores de custo do Oriveo são estimativas; os registros do serviço são os definitivos.
  • Se uma chave vazar, apague-a no painel do serviço e crie outra.

Por que o meu endpoint personalizado não conecta?

O Oriveo mostra em uma linha o que deu errado. As mensagens, como aparecem no app em português:

  • Para códigos como 401, 402 e 429, o nosso guia de erros de API key explica o que cada um significa.
Por que o meu endpoint personalizado não conecta?
Mensagem no OriveoO que conferir
O endereço pode estar apontando para uma página da web. Verifique se falta /v1.Compare o endereço com a documentação do serviço; acrescente ou tire o caminho de versão
A chave é inválida.Copie a chave de novo no painel do serviço
Esta chave não tem permissão para listar modelos. Você pode adicionar modelos manualmente.Adicione o ID do modelo você mesmo na etapa seguinte
Não foi possível conectar. Verifique sua rede ou proxy.Confira a sua conexão com a internet e se o endereço está acessível
O serviço neste endereço está limitando as solicitações.Espere um pouco e tente de novo
Esta conexão não conseguiu alcançar o provedor upstream.A conta do próprio serviço com o provedor por trás dele pode estar inválida, sem créditos ou com o limite de taxa atingido; fale com quem administra o serviço

Dúvidas comuns sobre o app

O que é um endpoint de API personalizado?
É o endereço da web de um serviço de IA que não vem integrado ao seu app, como uma API compatível com OpenAI, um relay ou um gateway. Você conecta digitando esse endereço (a Base URL) e uma API key do serviço.
O que é uma API compatível com OpenAI?
É uma API que aceita solicitações no mesmo formato da OpenAI, para que apps feitos para a OpenAI possam usá-la. Muitos provedores e gateways oferecem uma, geralmente em um endereço terminado em /v1.
Qual Base URL devo colocar?
A que está na documentação do serviço. Se ela trouxer só um domínio, digite assim mesmo, e o Oriveo acrescenta /v1 (ou /v1beta no formato do Gemini). Confira a linha "Será enviado para …" antes de continuar.
Dá para usar um endpoint personalizado no iPhone e no Android?
Sim. A Retransmissão personalizada está nos apps do Oriveo para iPhone e Android e no app web. No iPhone e no Android, o app se conecta diretamente ao endereço.
Por que o Oriveo exige HTTPS?
O HTTPS criptografa a conexão, então a sua chave e as suas mensagens não trafegam como texto aberto pela internet. Para um servidor de modelos na sua rede doméstica, use a entrada Computação local (no iPhone, Computação local e LAN).
É seguro usar um relay ou proxy de API?
Ele consegue ler tudo o que você envia por ele, então a confiança é o que mais importa. Use a chave que o serviço deu a você, nunca a do seu provedor oficial, defina um limite de gasto e não passe informações sensíveis por ele.

Leituras relacionadas

Do nosso blog

Conecte seu próprio serviço de modelos

Abra o app web ou baixe o Oriveo para iPhone ou Android, escolha Retransmissão personalizada e cole o endereço e a chave do seu serviço.

Ainda não tem uma chave de API? Comece com o Oriveo Free.