API LLM gratuita para agentes de IA
Um agente de IA envia muitas requisições ao modelo para uma única tarefa. Cada etapa precisa de tool calling e de um contexto grande. Um único nível gratuito esgota o agente rapidamente. O FreeLLMAPI reúne 45 níveis gratuitos de provedores atrás de uma única chave compatível com OpenAI. Ele passa para o próximo provedor quando um limite bloqueia uma requisição, para que o agente possa continuar. Este guia trata de tool calling, roteamento por etapa, sessões longas e do servidor MCP do roteador.
O código, os nomes dos modelos e os rótulos do catálogo ao vivo são exibidos em inglês.
O que um agente precisa de uma API gratuita
| Necessidade | Por quê | O que o FreeLLMAPI faz |
|---|---|---|
| Tool calling | O agente seleciona e executa ferramentas | Envia tools no formato OpenAI para cada provedor. Converte chamadas de ferramenta em texto simples em tool_calls reais. |
| Muitas requisições | Uma tarefa pode ter de 20 a 100 etapas | Conta a cota de cada chave e passa para a próxima chave ou provedor em caso de 429 |
| Contexto grande | Os resultados das ferramentas e o histórico crescem a cada etapa | Roteia para modelos da sua cadeia. Você pode criar um perfil de contexto longo. |
| Comportamento estável | Trocar de modelo no meio de uma tarefa pode confundir o agente | Mantém uma sessão no mesmo modelo por 30 minutos. Transferência de contexto opcional quando há uma troca. |
| Visibilidade | Você precisa saber qual modelo falhou | Cabeçalhos X-Routed-Via e X-Fallback-Trail em cada resposta |
Os níveis gratuitos têm limites. O failover distribui a carga entre suas chaves, mas o total ainda é a soma dos limites gratuitos. Para trabalho com agentes, adicione chaves de quatro ou mais provedores.
| Modelo | Gratuito em | Contexto | Limites gratuitos (melhor oferta) | Ferramentas | Visão |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 req/min 1 req/min per model | Sim | Não |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 req/min 40 RPM | Sim | Sim |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Sim | Sim |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Sim | Não |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 req/min 50 req/dia 50 req/day account-wide (1,000 after a $10 purchase) | Sim | Sim |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 req/min 50 req/dia Shared rate limit | Sim | Não |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 req/min 250 req/dia 70,000 tokens/min ~6M | Sim | Sim |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | Sim | Sim |
Mostrando 12 de 109 modelos gratuitos correspondentes. Ver todos os modelos.
Dados ao vivo do catálogo FreeLLMAPI (versão 2026.11.19, verificado em 2026-11-19). Os limites gratuitos mudam com frequência. O catálogo é verificado todos os dias.
Um loop completo de agente em Python
O loop abaixo usa o SDK oficial da OpenAI. Ele envia as ferramentas, executa cada chamada de ferramenta, devolve o resultado ao modelo e para quando o modelo dá uma resposta final. Ele também para após um número máximo de etapas.
agent.py
import json
import os
import time
import openai
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:3001/v1",
api_key=os.environ["FREELLMAPI_API_KEY"], # <unified-key>
max_retries=3,
)
def get_weather(city: str) -> dict:
return {"city": city, "temp_c": 18, "sky": "cloudy"}
TOOLS = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
FUNCTIONS = {"get_weather": get_weather}
def call_model(messages, session_id):
for attempt in range(5):
try:
return client.chat.completions.create(
model="auto:smart",
messages=messages,
tools=TOOLS,
extra_headers={"X-Session-Id": session_id},
)
except openai.RateLimitError as err:
header = err.response.headers.get("retry-after", "")
wait = int(header) if header.isdigit() else 2 ** attempt
time.sleep(min(wait, 60))
raise RuntimeError("All free providers are at their limit")
def run(task: str, session_id: str, max_steps: int = 10) -> str:
messages = [
{"role": "system", "content": "Use the tools when they help. Be brief."},
{"role": "user", "content": task},
]
for _ in range(max_steps):
msg = call_model(messages, session_id).choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
fn = FUNCTIONS.get(call.function.name)
try:
args = json.loads(call.function.arguments or "{}")
result = fn(**args) if fn else {"error": "unknown tool"}
except Exception as exc: # return tool errors to the model
result = {"error": str(exc)}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
return "Stopped: too many steps."
print(run("Should I take an umbrella in Dublin today?", session_id="task-001"))- X-Session-Id: mantém todas as etapas de uma tarefa no mesmo modelo enquanto esse modelo tiver cota.
- Retry-After: quando todas as chaves atingem o limite, o gateway retorna 429 com este cabeçalho. O loop espera e tenta de novo.
- Erros de ferramenta: o loop envia os erros de volta ao modelo como resultados de ferramenta. Assim, o modelo pode corrigir a chamada.
Roteie cada etapa para o modelo correto
As etapas de um agente não são iguais. Uma etapa de planejamento precisa de um modelo forte. Uma etapa que extrai um único campo precisa de um modelo rápido. Use uma string de modelo diferente para cada tipo de etapa. Você não precisa mudar o painel.
| String do modelo | Classifica os modelos por | Uso em agentes |
|---|---|---|
auto:smart | Inteligência | Planejamento, seleção de ferramentas, respostas finais |
auto:fast | Velocidade medida e tempo até o primeiro byte | Extração, classificação, resumos curtos de saída de ferramentas |
auto:reliable | Taxa de sucesso recente | Agentes agendados que precisam terminar |
auto:balanced | Confiabilidade primeiro, depois velocidade e inteligência | Padrão geral |
auto:<profile> | Sua cadeia de fallback nomeada | Uma cadeia só com modelos de tool calling |
As estratégias auto:* classificam todos os modelos habilitados e ignoram a ordem da sua cadeia. Uma requisição com ferramentas ainda precisa de um modelo com tool calling. Se alguns modelos habilitados não suportam bem as ferramentas, crie um perfil só com modelos de tool calling. Depois, use auto:<profile> nas etapas com ferramentas. Um nome de perfil desconhecido retorna erro 400.
O cabeçalho X-FreeLLM-Task-Type: code transfere o peso do roteamento de velocidade para inteligência, em uma requisição. É uma preferência leve. Ele não altera as verificações de capacidade nem a cadeia de fallback.
Sessões longas de agente e trocas de modelo
Durante uma tarefa longa, um modelo pode atingir o limite diário. O roteador então passa para outro modelo. O novo modelo recebe o histórico completo de mensagens, mas não sabe que outro modelo fez as etapas anteriores.
Ative a transferência de contexto para adicionar uma mensagem curta de sistema quando o modelo mudar. A mensagem diz ao novo modelo para continuar a tarefa e manter os resultados anteriores das ferramentas.
FreeLLMAPI .env
FREELLMAPI_CONTEXT_HANDOFF=on_model_switch- A mensagem de transferência é adicionada somente quando o modelo selecionado muda em uma sessão.
- As sessões ficam na memória por 3 horas. Nada é gravado em disco.
- A chave da sessão é o cabeçalho
X-Session-Id. Sem o cabeçalho, ela é um hash da primeira mensagem do usuário.
Use o roteador como servidor MCP
O FreeLLMAPI também é um servidor MCP em /mcp. Um agente que fala MCP pode enviar uma tarefa de texto a um modelo do FreeLLMAPI. Ele também pode ler o estado do gateway durante uma sessão: modelos disponíveis e seus parâmetros, saúde dos provedores, estatísticas de uso e cache, e a estratégia de roteamento.
A superfície MCP vem desligada em instalações novas. Ative-a no painel, na página Keys, em Agent compatibility. Enquanto estiver desligada, /mcp retorna 403.
Adicione o servidor MCP ao Claude Code
claude mcp add --transport http freellmapi http://localhost:3001/mcp \
--header "Authorization: Bearer <unified-key>"Qualquer cliente MCP com Streamable HTTP funciona da mesma forma. Aponte-o para /mcp e envie a chave unificada como token Bearer. Ferramentas úteis incluem healthcheck, list_models e ask_freellmapi. A ferramenta ask_freellmapi executa uma tarefa pela mesma rota de chat da API, com roteamento e fallback.
Para agentes de código, o FreeLLMAPI tem comandos de configuração que escrevem a configuração do cliente para você. Exemplos são npx freellmapi setup-claude, setup-codex, setup-cline, setup-openclaw e setup-hermes. Cada comando aceita --dry-run e cria um backup antes.
Solução de problemas
| Problema | Causa | Correção |
|---|---|---|
| O modelo responde em texto e não chama nenhuma ferramenta | O modelo tem tool calling fraco | Use auto:<profile> somente com modelos de tool calling |
| O agente reinicia a tarefa no meio | Um limite forçou a troca de modelo | Envie X-Session-Id e ative a transferência de contexto |
| Erro 429 após muitas etapas | Todas as chaves da cadeia atingiram o limite | Adicione provedores, use auto:fast para etapas pequenas e aguarde Retry-After |
Erro 400 com auto:name | O perfil não existe | Confira o nome do perfil no painel |
/mcp retorna 403 | A superfície MCP está desligada | Ative-a em Agent compatibility na página Keys |
| Erros de tamanho de contexto no fim de uma tarefa | O histórico é maior que a janela do modelo | Resuma resultados antigos de ferramentas ou use um perfil de contexto longo |
Perguntas frequentes
Existe uma API LLM gratuita para agentes de IA?
Sim. Vários provedores têm níveis gratuitos com tool calling. O FreeLLMAPI os combina atrás de uma única chave compatível com OpenAI e passa para o próximo provedor quando um limite bloqueia uma requisição.
Qual LLM gratuito é o melhor para tool calling?
Use um modelo com tool calling e uma janela de contexto de 128K tokens ou mais. A tabela desta página mostra os modelos gratuitos mais fortes que atendem às duas regras hoje.
Posso usar o FreeLLMAPI como servidor MCP?
Sim. Ative a superfície MCP na página Keys, em Agent compatibility. Depois, conecte seu cliente MCP a /mcp com a chave unificada como token Bearer.
Como impedir que um agente falhe por causa de limites de taxa?
Adicione chaves de mais provedores, envie etapas pequenas para auto:fast, tente de novo em caso de 429 com o cabeçalho Retry-After e defina um número máximo de etapas.
O que acontece quando o modelo muda no meio de uma tarefa de agente?
O novo modelo recebe o histórico completo de mensagens. Com a transferência de contexto ativa, ele também recebe uma nota curta que o orienta a continuar a tarefa.
Guias relacionados
- API LLM gratuita com function calling
- LLM gratuito em Python
- API LLM gratuita para LangChain
- API LLM gratuita para n8n
- Como usar o Claude Code gratuitamente
- Limites de taxa da API LLM gratuita
Fontes
- FreeLLMAPI docs: REST API (tool calling, routing strategies, response headers) (verificado em 20 November 2026)
- FreeLLMAPI docs: clients, MCP server and context handoff (verificado em 20 November 2026)
- OpenAI Python SDK: errors and retries (verificado em 20 November 2026)
- Claude Code docs: MCP (verificado em 20 November 2026)