Endpoints do AI Gateway e Variáveis de Ambiente

Além de tomar controle com um clique de ferramentas de IA prontas, você também pode chamar o AI Gateway diretamente em seus próprios aplicativos, scripts ou em qualquer ferramenta de IA. Este artigo apresenta os formatos de endpoint expostos pelo gateway, bem como como conectar utilizando chaves virtuais.

Endpoints Proxy

O serviço proxy do AI Gateway escuta em http://127.0.0.1:11580. Para garantir compatibilidade com SDKs e ferramentas de diferentes fornecedores, o gateway oferece vários formatos de endpoint no mesmo porto:

Formato de Protocolo	Caminho do Endpoint	Cenário de Uso
Compatível OpenAI	http://127.0.0.1:11580/v1	Qualquer SDK/ferramenta que use o formato de API da OpenAI (por exemplo, /v1/chat/completions)
Compatível Anthropic	http://127.0.0.1:11580/v1/messages	SDK da Anthropic e Claude Code, por exemplo
Compatível Gemini	http://127.0.0.1:11580/v1beta	SDK Google Gemini, Gemini CLI, etc.

Basta selecionar o formato correspondente ao protocolo do seu SDK e direcionar as requisições ao endereço do gateway. O gateway irá rotear suas chamadas, de acordo com as permissões da chave virtual, para o canal do fornecedor.

Autenticação: Usando Chaves Virtuais

Todas as requisições para o gateway usam chaves virtuais para autenticação, não as chaves reais do fornecedor. Primeiro, crie uma chave virtual e copie o valor no painel de Chaves.

Na página AI Gateway → Endpoints, você pode selecionar uma chave virtual e o gateway irá gerar automaticamente trechos de variáveis de ambiente prontos para uso nas ferramentas mais populares.

Exemplos de Variáveis de Ambiente

Os exemplos a seguir assumem que você já obteve uma chave virtual válida (substitua por <sua-chave-virtual>).

SDKs / Ferramentas Compatíveis com OpenAI

export OPENAI_BASE_URL="http://127.0.0.1:11580/v1"
export OPENAI_API_KEY="<sua-chave-virtual>"

Claude Code / Anthropic

# Observação: O protocolo Anthropic usa a raiz do gateway, sem /v1
export ANTHROPIC_BASE_URL="http://127.0.0.1:11580"
export ANTHROPIC_AUTH_TOKEN="<sua-chave-virtual>"

Gemini

export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:11580"
export GEMINI_API_KEY="<sua-chave-virtual>"

Exemplo de Uso (Compatível OpenAI)

curl http://127.0.0.1:11580/v1/chat/completions \
  -H "Authorization: Bearer <sua-chave-virtual>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Olá"}]
  }'

O campo model precisa ser um modelo já configurado em seus canais e permitido para a chave virtual utilizada.

Pré-requisitos

• O serviço proxy do AI Gateway está em execução.
• Pelo menos um canal saudável foi configurado, e já existe uma chave virtual com permissão para acessar o modelo/canal correspondente.

FAQ (Perguntas Frequentes)

• P: Minha requisição está retornando falha de autenticação?
  • R: Certifique-se de estar utilizando uma chave virtual (não a chave real do fornecedor), e que ela não está expirada nem foi revogada.
• P: Recebo aviso de modelo indisponível ou sem permissão?
  • R: Confirme se o model foi configurado em algum canal e se a chave virtual possui permissão de acesso ao modelo/canal em questão.
• P: Qual formato de endpoint devo usar?
  • R: Escolha de acordo com o protocolo do seu SDK — estilo OpenAI usa /v1, estilo Anthropic usa /v1/messages (o Base URL não inclui /v1), e estilo Gemini usa /v1beta.
• P: Outros dispositivos da rede local podem acessar o gateway?
  • R: Por padrão, o gateway escuta somente em 127.0.0.1 (somente na máquina local), por motivos de segurança. Esta configuração é recomendada.

Resumo

O AI Gateway oferece endpoints locais unificados nos formatos compatíveis OpenAI, Anthropic e Gemini. Com autenticação via chave virtual, você pode conectar qualquer app ou ferramenta de IA ao gateway, gerenciando permissões e monitorando o uso de forma centralizada. Para CLIs populares, utilize o recurso de tomar controle com um clique para integração ainda mais fácil.