LLM gratuito em Python
O pacote oficial openai para Python funciona com qualquer API compatível com OpenAI. Você troca a base URL e a chave. Este guia usa o FreeLLMAPI, que reúne 45 camadas gratuitas de provedores atrás de uma única chave e passa para o próximo provedor quando um limite interrompe uma requisição. Cada exemplo abaixo está completo e roda como está.
O código, os nomes dos modelos e os rótulos do catálogo ao vivo são exibidos em inglês.
Configuração
Instale o FreeLLMAPI. Ele roda no Docker. Abra o painel em http://localhost:3001, adicione chaves gratuitas de dois ou mais provedores na página Keys e copie a chave unificada. Depois, instale o pacote Python.
O seu código Python usa somente a chave unificada. As chaves dos provedores ficam no FreeLLMAPI, criptografadas no banco de dados dele. Se você trocar ou adicionar uma chave de provedor, não precisa mudar o seu código.
Instalação
curl -fsSL https://freellmapi.co/install.sh | bash
python3 -m pip install -U openai
export FREELLMAPI_API_KEY=<unified-key>client.py
import os
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:3001/v1",
api_key=os.environ["FREELLMAPI_API_KEY"],
max_retries=3, # the SDK retries 429, 408, 409 and 5xx errors
timeout=60,
)
resp = client.chat.completions.create(
model="auto",
messages=[{"role": "user", "content": "Name three uses of Python in one line."}],
)
print(resp.choices[0].message.content)O modelo auto segue a sua cadeia de fallback no painel. Você também pode usar auto:fast, auto:smart ou auto:reliable, um perfil como auto:coding, ou um ID de modelo fixo.
Streaming e cabeçalhos de resposta
Receba a resposta em streaming
from client import client
stream = client.chat.completions.create(
model="auto:fast",
messages=[{"role": "user", "content": "Write a haiku about Python."}],
stream=True,
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="", flush=True)
print()Cada resposta tem um cabeçalho X-Routed-Via com o provedor e o modelo que responderam. Para ler os cabeçalhos com o SDK, use with_raw_response e chame parse() para obter o objeto normal.
Leia os cabeçalhos de roteamento
from client import client
raw = client.chat.completions.with_raw_response.create(
model="auto",
messages=[{"role": "user", "content": "hi"}],
)
print("Served by:", raw.headers.get("x-routed-via"))
print("Failed attempts:", raw.headers.get("x-fallback-attempts", "0"))
print(raw.parse().choices[0].message.content)Chamada de ferramentas
Envie tools no estilo OpenAI. O roteador as passa para os provedores compatíveis com OpenAI e as traduz para o Gemini. A resposta volta no mesmo formato para todos os provedores.
Uma chamada de ferramenta e a resposta final
import json
from client import client
tools = [{
"type": "function",
"function": {
"name": "get_exchange_rate",
"description": "Get the exchange rate between two currencies.",
"parameters": {
"type": "object",
"properties": {
"base": {"type": "string"},
"quote": {"type": "string"},
},
"required": ["base", "quote"],
},
},
}]
messages = [{"role": "user", "content": "How many euros is 250 US dollars?"}]
first = client.chat.completions.create(model="auto", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
result = {"base": args["base"], "quote": args["quote"], "rate": 0.92} # your real lookup
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
final = client.chat.completions.create(model="auto", messages=messages, tools=tools)
print(final.choices[0].message.content)
else:
print(msg.content)Alguns provedores retornam uma chamada de ferramenta como texto simples. O FreeLLMAPI converte essas respostas em tool_calls reais, então o seu código lê um só formato. Sempre verifique msg.tool_calls antes de ler msg.content, porque um modelo também pode responder sem usar uma ferramenta.
Use um modelo com chamada de ferramentas. Estes modelos gratuitos suportam ferramentas e têm a velocidade medida mais alta hoje:
| Modelo | Gratuito em | Contexto | Limites gratuitos (melhor oferta) | Ferramentas | Visão |
|---|---|---|---|---|---|
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 req/min 250 req/dia 70,000 tokens/min ~6M | Sim | Sim |
| Nemotron 3.5 Lightning | ElectronHub, Kilo Gateway, OpenRouter | 1M | 20 req/min 50 req/dia 50 req/day account-wide (1,000 after a $10 purchase) | Sim | Não |
| GPT-OSS 120B | Cloudflare Workers AI, ElectronHub, Groq +1 a mais | 131K | 30 req/min 1,000 req/dia 8,000 tokens/min 200,000 tokens/dia ~6M | Sim | Não |
| GPT-OSS 20B | Cloudflare Workers AI, Groq, NVIDIA NIM +1 a mais | 131K | 30 req/min 1,000 req/dia 8,000 tokens/min 200,000 tokens/dia ~6M | Sim | Não |
| GPT-OSS Safeguard 20B | Groq | 131K | 30 req/min 1,000 req/dia 8,000 tokens/min 200,000 tokens/dia ~6M | Sim | Não |
| Gemini 3.5 Flash Lite | ElectronHub, Google AI Studio | 1M | 15 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Step 3.7 Flash | ElectronHub | 256K | $0.25/week shared recurring credit | Sim | Sim |
| Gemini 3.1 Flash-Lite | DreamPrompting, Google AI Studio | 1M | 100 req/min 5,000 req/dia 500,000 tokens/dia 500K tokens/day · 5,000 req/day | Sim | Sim |
| Nemotron 3.5 Lightning 30B | Requesty | 1M | 200 req/dia 200 rpd | Sim | Não |
| Gemini 2.5 Flash-Lite | ElectronHub, Google AI Studio | 1M | 15 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
Mostrando 10 de 146 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.
Lotes assíncronos dentro dos limites gratuitos
AsyncOpenAI envia muitas requisições ao mesmo tempo. As camadas gratuitas limitam as requisições por minuto, então limite a concorrência com um semáforo. O exemplo também faz novas tentativas quando todos os provedores estão no limite.
batch.py
import asyncio
import os
import openai
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="http://localhost:3001/v1",
api_key=os.environ["FREELLMAPI_API_KEY"],
max_retries=2,
)
limit = asyncio.Semaphore(4) # at most 4 requests at a time
async def summarize(text: str) -> str:
async with limit:
for attempt in range(5):
try:
resp = await client.chat.completions.create(
model="auto:fast",
messages=[
{"role": "system", "content": "Summarize in one sentence."},
{"role": "user", "content": text},
],
)
return resp.choices[0].message.content
except openai.RateLimitError as err:
header = err.response.headers.get("retry-after", "")
wait = int(header) if header.isdigit() else 2 ** attempt
await asyncio.sleep(min(wait, 60))
return "ERROR: rate limited"
async def main():
docs = [f"Document {i}: Python is a programming language." for i in range(20)]
results = await asyncio.gather(*(summarize(d) for d in docs))
for r in results:
print(r)
await client.close()
asyncio.run(main())O roteador retorna 429 somente quando todas as chaves da cadeia estão no limite. A resposta então tem um cabeçalho Retry-After. Um valor pequeno de semáforo e mais chaves de provedores dão os melhores resultados em lotes grandes.
Escolha uma string de modelo para cada tarefa
A string de modelo diz ao roteador como selecionar um modelo. Você pode usar uma string diferente em cada chamada. Não é preciso mudar o painel.
| Tarefa | String de modelo | Motivo |
|---|---|---|
| Respostas de chat para usuários | auto | Segue a cadeia de fallback que você definiu no painel |
| Classificação, extração, resumos curtos | auto:fast | Ordena os modelos habilitados pela velocidade medida |
| Perguntas difíceis, revisão de código, planejamento | auto:smart | Ordena os modelos habilitados pela inteligência |
| Tarefas agendadas que precisam terminar | auto:reliable | Ordena os modelos habilitados pela taxa de sucesso recente |
| Uma cadeia separada para um app | auto:<profile> | Usa uma cadeia de fallback com nome |
| Testes que precisam ser repetíveis | Um ID de modelo fixo | O mesmo modelo sempre, mas para no limite desse modelo |
Para ver quais modelos as suas chaves podem chamar agora, peça a lista de modelos com um filtro. A lista completa também contém modelos que ainda não têm chave.
Liste os modelos que podem responder agora
import os
import httpx
r = httpx.get(
"http://localhost:3001/v1/models",
params={"execution_status": "ready"},
headers={"Authorization": f"Bearer {os.environ['FREELLMAPI_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
for m in r.json()["data"]:
print(m["id"])Um modelo com o status exhausted tem chaves, mas todas estão no limite agora. O status é limpo quando os períodos de espera terminam. Um modelo com o status needsKey não tem nenhuma chave habilitada.
Para uma conversa, envie um cabeçalho X-Session-Id com extra_headers. O FreeLLMAPI então mantém essa conversa no mesmo modelo por 30 minutos. Sem o cabeçalho, ele usa um hash da primeira mensagem do usuário como chave da sessão.
Embeddings
Gere embeddings de texto
from client import client
resp = client.embeddings.create(
model="bge-m3", # one embedding family
input=["Python is a programming language.", "A snake is a reptile."],
)
print(len(resp.data), "vectors of", len(resp.data[0].embedding), "dimensions")O failover de embeddings nunca troca o modelo. Ele só passa entre provedores que atendem a mesma família, então os seus vetores continuam compatíveis. O valor auto usa a família padrão que você definiu no painel.
Envie muitos textos em uma só lista input. Uma requisição com 32 textos usa uma requisição da cota gratuita, e não 32. Mantenha cada texto abaixo da entrada máxima da família. Guarde o nome da família junto com os seus vetores, para gerar os embeddings das consultas com a mesma família depois.
Erros e correções
| Exceção | Causa | Solução |
|---|---|---|
openai.AuthenticationError | Chave unificada errada | Copie a chave de novo na página Keys |
openai.APIConnectionError | O FreeLLMAPI não está em execução, ou a porta está errada | Abra http://localhost:3001 no navegador |
openai.NotFoundError | A base URL não tem /v1 | Use http://localhost:3001/v1 |
openai.RateLimitError | Todas as chaves da cadeia estão no limite | Adicione provedores, reduza a concorrência, aguarde o Retry-After |
openai.BadRequestError com auto:name | O nome do perfil não existe | Confira o nome do perfil no painel |
openai.UnprocessableEntityError (422) com imagens | Nenhum modelo de visão está na sua cadeia | Habilite um modelo de visão na cadeia de fallback |
As camadas gratuitas não têm SLA. A latência muda ao longo do dia. Os modelos mais fortes atingem primeiro os limites diários, e muitos limites são renovados à meia-noite UTC. Não use um gateway gratuito para um serviço que precisa responder em um tempo fixo.
Perguntas frequentes
Existe uma API gratuita de LLM para Python?
Sim. Muitos provedores têm camadas gratuitas que funcionam com o pacote openai para Python. O FreeLLMAPI as combina atrás de uma base URL e uma chave, com failover entre provedores.
Como uso a biblioteca openai do Python com outra base URL?
Passe base_url para OpenAI() ou AsyncOpenAI(), por exemplo base_url="http://localhost:3001/v1". Passe a chave do seu gateway como api_key.
Como trato erros de limite de taxa em Python?
Defina max_retries no cliente. Capture openai.RateLimitError, leia o cabeçalho Retry-After e aguarde. Limite a concorrência com um semáforo do asyncio.
O streaming funciona com APIs gratuitas de LLM em Python?
Sim. Passe stream=True e leia chunk.choices[0].delta.content. O FreeLLMAPI faz streaming no formato OpenAI para todos os provedores.
Posso usar Python assíncrono com uma API gratuita de LLM?
Sim. Use AsyncOpenAI com a mesma base_url e chave. Mantenha pequeno o número de requisições paralelas, porque as camadas gratuitas limitam as requisições por minuto.
Guias relacionados
- URLs base de APIs gratuitas compatíveis com OpenAI
- API LLM gratuita para LangChain
- API LLM gratuita para agentes de IA
- API LLM gratuita com function calling
- Limites de taxa da API LLM gratuita
Fontes
- OpenAI Python SDK README (async, retries, raw responses, errors) (verificado em 20 November 2026)
- FreeLLMAPI docs: REST API (chat, streaming, tool calling, embeddings, headers) (verificado em 20 November 2026)
- FreeLLMAPI docs: degraded mode and failover (verificado em 20 November 2026)