Endpoints e variáveis de ambiente do Gateway de IA

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

Endpoint de proxy

O serviço de proxy do Gateway de IA escuta em http://127.0.0.1:11580. Para ser compatível com SDKs e ferramentas de diferentes fornecedores, o gateway oferece endpoints em vários formatos de protocolo na mesma porta:

Formato de protocolo	Caminho do endpoint	Cenário de uso
Compatível com OpenAI	http://127.0.0.1:11580/v1	Qualquer SDK/ferramenta que use o formato da API OpenAI (ex.: /v1/chat/completions)
Compatível com Anthropic	http://127.0.0.1:11580/v1/messages	SDK da Anthropic, Claude Code etc.
Compatível com Gemini	http://127.0.0.1:11580/v1beta	SDK do Google Gemini etc.

Basta escolher o formato correspondente ao protocolo do SDK usado e direcionar as requisições para o endereço do gateway. O gateway roteia as requisições para o canal do fornecedor correspondente com base nas permissões da chave virtual.

Autenticação: usando uma chave virtual

Todas as requisições ao gateway são autenticadas com uma chave virtual, e não com a chave real do fornecedor. Primeiro, crie uma chave virtual na página Chaves e copie seu valor em texto claro.

Na página Gateway de IA → Endpoints, você pode selecionar uma chave virtual, e o gateway gera diretamente trechos de variáveis de ambiente prontos para copiar para as ferramentas mais usadas.

Exemplos de variáveis de ambiente

Os exemplos abaixo assumem que você já obteve uma chave virtual (representada como <你的虚拟密钥>).

SDK/ferramentas compatíveis com OpenAI

export OPENAI_BASE_URL="http://127.0.0.1:11580/v1"
export OPENAI_API_KEY="<你的虚拟密钥>"

Claude Code / Anthropic

# Observação: o protocolo Anthropic usa o endereço raiz do gateway, sem /v1
export ANTHROPIC_BASE_URL="http://127.0.0.1:11580"
export ANTHROPIC_AUTH_TOKEN="<你的虚拟密钥>"

Gemini

export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:11580"
export GEMINI_API_KEY="<你的虚拟密钥>"

Exemplo de chamada (compatível com OpenAI)

curl http://127.0.0.1:11580/v1/chat/completions \
  -H "Authorization: Bearer <你的虚拟密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

O model deve ser um modelo que você já configurou em um canal e que a chave virtual tem permissão para chamar.

Pré-requisitos

• O serviço de proxy do Gateway de IA está em execução.
• Pelo menos um canal saudável está configurado e uma chave virtual com permissão para os modelos/canais correspondentes foi criada.

Perguntas frequentes (FAQ)

• P: A requisição retorna falha de autenticação?
  • R: Confirme se está usando uma chave virtual (e não a chave real do fornecedor), e se a chave não expirou nem foi revogada.
• P: Aparece que o modelo não está disponível ou sem permissão?
  • R: Confirme se esse model está configurado em algum canal e se os “modelos/canais permitidos” da chave virtual atual incluem ele.
• P: Qual formato de endpoint devo usar?
  • R: Escolha de acordo com o protocolo do SDK usado — para o estilo OpenAI use /v1; para o estilo Anthropic use /v1/messages (a URL base não inclui /v1); para o estilo Gemini use /v1beta.
• P: Outros dispositivos na rede local conseguem acessar o gateway?
  • R: Por padrão, o gateway escuta apenas em 127.0.0.1 (somente máquina local). Essa é a configuração recomendada por segurança.

Resumo

O Gateway de IA fornece endpoints locais unificados nos três formatos compatíveis: OpenAI, Anthropic e Gemini. Com a autenticação por chave virtual, você pode conectar qualquer aplicativo ou ferramenta de IA ao gateway e aproveitar o gerenciamento unificado de chaves e as estatísticas de uso. Para ferramentas CLI comuns, usar a tomada de controle com um clique diretamente é mais prático.