Documentação Oficial
A Thrifty AI é um Gateway de Inteligência Artificial focado em economia e performance. Ela atua como um intermediário inteligente entre sua aplicação (n8n, Typebot, Código) e os provedores de LLM.
Cache Inteligente
Respostas repetidas são entregues instantaneamente.
Roteamento
Redireciona automaticamente para DeepSeek, Groq, Google, etc.
Unificação
Uma única API Key para acessar múltiplos modelos.
Autenticação
Todas as requisições devem ser feitas para o Base URL abaixo, autenticadas via Bearer Token.
https://api.thrifty.qzz.io/v1Sua chave sk-thrifty-... deve ser enviada no Header Authorization. Nunca exponha essa chave em scripts públicos (frontend).
Universal / Custom & Prioridade
Além dos provedores nativos (OpenAI, Groq, etc), você pode adicionar qualquer API compatível com OpenAI na aba "Universal / Custom" do Dashboard.
Ordem de Prioridade (Roteamento)
Quando você envia uma requisição, o Thrifty decide qual provedor usar seguindo esta lógica estrita:
- 1Match Customizado: Se o nome do modelo solicitado contiver o nome de um provedor Custom que você adicionou (ex: "mistral"), ele usará a sua configuração customizada.
- 2Nativos Específicos: Se detectar
claude,gemini,llama, etc., usará as chaves nativas configuradas. - 3OpenRouter: Se o modelo tiver uma barra
/(ex:google/gemini-pro) e não caiu nas regras acima, vai para a OpenRouter. - 4Fallback: Se nada for identificado, a requisição vai para a OpenAI.
Parâmetros de Controle
Você pode controlar a criatividade e o comportamento da IA enviando estes parâmetros opcionais no JSON:
stream IMPORTANTE
Tipo: boolean (Padrão: false para requests curtos, true em libs)
true: A resposta chega em pedaços (Server-Sent Events). Ideal para chats em tempo real.false: A API espera a resposta completa e retorna um único JSON. Essencial para ver o consumo de tokens (usage) e para automações (n8n, Typebot).
temperature
Range: 0.0 a 2.0 (Padrão: 0.7)
- Baixa (0.1): Fatos, lógica, código preciso. Respostas determinísticas.
- Alta (0.9+): Criatividade, poemas, brainstorming. Mais imprevisível.
top_p
Range: 0.0 a 1.0 (Padrão: 1)
Controla a diversidade do vocabulário. Use 0.1 para respostas muito focadas ou 1.0 para vocabulário rico.
useContext RAG
Habilita o modo de Geração Aumentada por Recuperação (RAG). Se definido como true, a IA usará logs passados do seu banco de dados como "memória" para responder.
messages (System Prompt)
Defina a "personalidade" ou regras da IA usando o papel system no início do array de mensagens.
"messages": [
{ "role": "system", "content": "Você é um especialista em Marketing." },
{ "role": "user", "content": "Crie um post sobre café." }
]Estrutura da Resposta & Tokens
A Thrifty segue o padrão da OpenAI. Entenda como identificar se houve economia (Cache) através do objeto usage.
{
"id": "chatcmpl-123...",
"object": "chat.completion",
"created": 1709223344,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "A resposta da IA..."
},
"finish_reason": "stop"
}
],
"usage": { <-- ONDE OLHAR
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}Entendendo o Consumo
MISS (Sem Cache): A requisição foi enviada para o provedor (OpenAI, Groq) e consumiu créditos reais.
HIT (Com Cache): A resposta veio do banco de dados. Você economizou 100% do custo desta requisição.
Smart Cache & RAG
O Thrifty armazena automaticamente perguntas e respostas para economizar seus créditos. Você pode controlar esse comportamento via Headers.
| Header | Valores | Descrição |
|---|---|---|
| x-thrifty-use-cache | true | false | Força o uso do cache semântico mesmo usando chaves externas (Groq/OpenAI). |
| x-thrifty-refresh | true | Ignora o cache existente e força uma nova geração na LLM (revalidação). Útil quando você sabe que a resposta mudou. |
O cache utiliza vetores para comparar perguntas. Isso requer uma conexão ativa com a API (OpenAI/Google). Se sua chave estiver sem saldo, o cache pode falhar com erro 429.
Inteligência Temporal
Para evitar que o cache entregue respostas antigas para perguntas que exigem dados frescos (ex: "Qual a cotação do Dólar?"), o Thrifty possui um sistema de detecção temporal.
Modo Default
Usa a lista padrão do sistema.
Modo Custom
Ignora a lista do sistema e usa apenas as suas.
Modo Hybrid
Combina as duas listas.
Privacidade & BYOD
Bring Your Own Database (BYOD)
Clientes do plano Ultra podem conectar seu próprio cluster MongoDB Atlas.
Requisitos de Segurança
- Cluster MongoDB (versão 6.0+)
- Obrigatório: Criação manual do Search Index
Modelos e Roteamento
Basta mudar o parâmetro model no JSON para trocar de provedor.
| Prefixo Modelo | Provedor | Exemplo |
|---|---|---|
| gpt-*, text-* | OpenAI | gpt-4o |
| llama-* | Groq | llama-3.3-70b-versatile |
| gemini-* | gemini-pro | |
| claude-* | Anthropic | claude-3-5-sonnet |
| */* (Barra) | OpenRouter | google/gemini... |
Integração n8n (Nó OpenAI)
A maneira mais fácil de usar a Thrifty no n8n é utilizando o nó oficial da OpenAI.
Adicione o nó 'OpenAI Chat Model'
Configure a Credencial
Ajuste Crítico
Integração n8n / Typebot (HTTP Request)
Para controle total ou uso no Typebot, use o bloco de requisição HTTP nativo.
{
"model": "gpt-4o-mini",
"temperature": 0.7,
"stream": false,
"messages": [
{
"role": "user",
"content": "Olá, tudo bem?"
}
]
}Exemplos de Código
curl -X POST https://api.thrifty.qzz.io/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-thrifty-..." \
-H "x-thrifty-use-cache: true" \
-d '{
"model": "deepseek/deepseek-chat",
"temperature": 0.7,
"stream": false,
"messages": [{"role": "user", "content": "Olá!"}]
}'