Documentação da API | AegisFlow — LLM Gateway compatível com OpenAI

1 Visão geral

Existem dois planos de acesso, com credenciais diferentes:

Plano de dados (suas aplicações): autentica com uma chave do AegisFlow no header x-api-key. É por aqui que passam as chamadas de IA.
Painel (você/seu time): login via Supabase para gerenciar chaves, credenciais BYOK, ver uso e cobrança.

Base URL: https://aegisflow.tech/v1 (produção) — em dev, http://localhost:8000/v1.

2 Autenticação

Toda chamada ao proxy exige o header x-api-key com uma chave gerada no painel (formato agf_....). A chave em claro é mostrada uma única vez, na criação.

x-api-key: agf_a1b2c3d4.seu-segredo-aqui

Sem a chave → 401. Chave inválida/revogada → 403.

3 Quickstart

Use qualquer SDK compatível com OpenAI — só muda a base_url e a chave:

from openai import OpenAI

client = OpenAI(
    base_url="https://aegisflow.tech/v1",
    api_key="agf_a1b2c3d4.•••••",   # sua chave do AegisFlow
)

resp = client.chat.completions.create(
    model="aegis-auto",              # roteamento automático por complexidade
    messages=[{"role": "user", "content": "Escreva testes para esta função"}],
)
print(resp.choices[0].message.content)

4 Chat Completions plano de dados

POST /v1/chat/completions

Proxy compatível com o formato OpenAI. Resolve a credencial BYOK do tenant, chama o provedor real (qualquer LLM, na nuvem ou local) e devolve a resposta. Suporta streaming (SSE) com "stream": true.

Campos: model, messages, provider (opcional), stream, max_tokens, temperature, fallback.

curl https://aegisflow.tech/v1/chat/completions \
  -H "x-api-key: agf_..." -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Olá!"}]
  }'

5 Roteamento — `aegis-auto`

Ao enviar "model": "aegis-auto", o gateway classifica a complexidade e escolhe a rota mais econômica, com política local-first + escalonamento:

Local é o primeiro recurso (gratuito), para tarefas simples e complexas.
Se o local não der conta (falha/indisponível), escala para um modelo pago — o premium no caso de tarefa complexa.
Sem provedor local, escolhe direto o hospedado mais adequado ao tier.

A decisão vem nos headers (x-aegis-model, x-aegis-complexity, x-aegis-routed) e a economia entra em Uso & Economia.

6 Fallback

Defina uma cadeia de reserva: se o modelo principal falhar, o gateway tenta os próximos automaticamente.

{
  "model": "gpt-4o-mini",
  "messages": [...],
  "fallback": ["google:gemini-2.5-flash", "ollama:qwen3.5:4b"]
}

Cada item é provider:model ou apenas model (o provedor é inferido).

7 Cache semântico

Requisições semanticamente parecidas não pagam duas vezes. Comparamos o prompt (via embeddings) com respostas anteriores do tenant; se a similaridade passar do limite, servimos do cache em milissegundos — sem chamar o provedor. O header x-aegis-cache indica hit ou miss.

Configurável por tenant: limite de similaridade e TTL. Prompts diferentes não colidem.

8 Modelos plano de dados

GET /v1/models

Lista, no formato OpenAI, os modelos disponíveis nos provedores que o seu tenant cadastrou (consulta cada provedor em tempo real).

9 Embeddings plano de dados

POST /v1/embeddings

Gera embeddings via BYOK (OpenAI-compatível ou Ollama). Retorna no formato OpenAI.

curl https://aegisflow.tech/v1/embeddings \
  -H "x-api-key: agf_..." -H "Content-Type: application/json" \
  -d '{"provider": "openai", "model": "text-embedding-3-small", "input": "olá"}'

10 Credenciais BYOK painel

Cadastre as chaves dos seus provedores (OpenAI, Anthropic, Gemini, Qwen…) ou aponte para um modelo local (Ollama, LM Studio, vLLM). Ficam cifradas em repouso com AES-256-GCM e só são descriptografadas em memória, no instante da chamada.

GET /v1/admin/provider-keys

POST /v1/admin/provider-keys

Campos: provider, api_key (opcional p/ locais), base_url, format (openai/anthropic/ollama), label, default_model.

11 Chaves & limites painel

POST /v1/admin/keys

PATCH /v1/admin/keys/{id}

Crie chaves de API para suas apps e defina limites por chave (chaves virtuais): orçamento mensal (USD), rate limit (rpm) e allowlist de modelos. A chave só usa os modelos permitidos e para ao atingir o orçamento.

12 Uso & Economia painel

GET /v1/admin/usage/summary

GET /v1/admin/logs

O resumo mostra tokens e custo por LLM, com o comparativo "se tudo rodasse no mesmo LLM" (economia auditável). Os logs trazem cada requisição (modelo, tokens, custo, latência, status, cache). Prévias de prompt/resposta são opt-in e sempre com redação de PII (LGPD).

13 Planos & Cobrança painel

GET /v1/admin/billing

Planos em BRL com quota mensal e rate limit por plano. Cobrança da orquestração — o consumo dos modelos é pago direto na sua chave (BYOK), sem markup sobre tokens.

14 Headers de resposta

x-aegis-request-id — id da requisição (rastreio nos logs).
x-aegis-model / x-aegis-provider — modelo e provedor usados.
x-aegis-cache — hit ou miss.
x-aegis-complexity / x-aegis-routed / x-aegis-local — decisão do aegis-auto.

15 Segurança & LGPD

BYOK cifrado em repouso (AES-256-GCM); chaves nunca em logs.
Redação de PII (CPF, CNPJ, e-mail, telefone, cartão) nos logs e, opcionalmente, antes de enviar a provedores hospedados.
Isolamento por tenant, rate limit e quotas.
Proteção anti-SSRF nos endpoints de provedor.

Documentação