LLM4Free

One Python toolkit for 40+ free & paid AI models, web search, image & voice generation, and a drop-in OpenAI-compatible server — all behind a single, consistent interface.

✨ Why LLM4Free?

Most AI libraries lock you into one provider and one way of doing things. LLM4Free gives you everything behind the interface you already know — the OpenAI SDK:

• 🔌 One interface, 40+ providers. Every chat provider implements client.chat.completions.create(...) — identical to the OpenAI Python SDK. Switch providers by changing one line.
• 💸 Free tier built in. Use HeckAI, Pollinations, and more with zero API key — then graduate to Groq, DeepInfra, or your own key when you need scale.
• 🔄 Auto-failover client. The unified Client retries across providers and resolves models for you. No more 3am outages from a dead endpoint.
• 🔍 Multi-engine search. DuckDuckGo, Bing, Brave, Yahoo, Mojeek, Wikipedia — one API.
• 🖼️🗣️ Images & voice. Text-to-image (Pollinations, Together, Stable Horde…) and text-to-speech (ElevenLabs, OpenAI FM, Qwen, Murf…) out of the box.
• 🚀 OpenAI-compatible server. Serve any provider through standard /v1 endpoints — point the official OpenAI SDK at your laptop.
• 🧰 Developer toolbox. Web crawler (Scout), GitHub data toolkit, temp-mail, GGUF conversion, user-agent rotation, ASCII art, and more.
• 📚 Fully typed & documented. 100% type-annotated public API with auto-generated MkDocs reference.

📦 Installation

# pip
pip install -U llm4free

# With the OpenAI-compatible API server
pip install -U "llm4free[api]"

# With development tools
pip install -U "llm4free[dev]"

# uv (recommended)
uv add llm4free

# Run without installing
uv run llm4free --help

# Install as a global CLI tool
uv tool install llm4free

# Docker
docker pull OEvortex/llm4free:latest
docker run -it OEvortex/llm4free:latest

See docs/DOCKER.md for full Docker deployment options including compose profiles.

🚀 Quick Start

Unified Client — one client for everything

The fastest way to use LLM4Free is the unified Client. It behaves just like the OpenAI SDK you already know, but it picks a working provider for you and auto-fails over when one is down. Use model="auto" to let it choose, or model="Provider/Model" to force a specific one.

from llm4free.client import Client

# Let the client pick any working provider/model
client = Client(print_provider_info=True)
response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Explain quantum computing in simple terms"}],
)
print(response.choices[0].message.content)

# Or force a specific provider/model explicitly
client.chat.completions.create(
    model="HeckAI/google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Hello!"}],
)

AI Chat — no API key required (raw provider)

Prefer to use a provider directly? Every provider implements the OpenAI-compatible interface. The Client above is the recommended path because it adds auto-failover and model resolution automatically.

from llm4free.llm.heckai import HeckAI

client = HeckAI()
response = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Explain quantum computing in simple terms"}],
)
print(response.choices[0].message.content)

Web Search

from llm4free import DuckDuckGoSearch

search = DuckDuckGoSearch()
results = search.text("best practices for API design", max_results=5)
for result in results:
    print(f"{result['title']}: {result['href']}")

Image Generation

The same unified Client does images OpenAI-style — client.images.generate(...) (alias client.images.create(...)). Use model="auto" for automatic provider selection and failover, or pin a backend with model="Provider/Model".

from llm4free.client import Client

client = Client(print_provider_info=True)

# Auto-select a working image provider
image = client.images.generate(
    prompt="A serene mountain landscape at sunset",
    model="auto",
    size="1024x1024",
)
print(image.data[0].url)

# Or force a specific backend
image = client.images.generate(
    prompt="A cyberpunk city at night",
    model="PollinationsAI/flux",
)
print(image.data[0].url)

Prefer a provider directly? Every TTI provider implements the OpenAI-style images.create(...) method too:

from llm4free.Provider.TTI import PollinationsAI

gen = PollinationsAI()
image = gen.images.create(prompt="A serene mountain landscape at sunset", response_format="url")
print(image.data[0].url)

Unified Client — recall the hero example

The unified Client shown at the top of Quick Start is the recommended way to use LLM4Free: model="auto" picks a working provider, model="Provider/Model" forces a specific one, and it auto-fails over between providers.

from llm4free.client import Client

client = Client(print_provider_info=True)
resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarize LLM4Free."}],
)
print(resp.choices[0].message.content)

See docs/getting-started.md for the full quick-start guide.

💻 Command Line Interface

A rich CLI powered by Rich — search, chat, and generate straight from your terminal.

llm4free --help                       # List all commands
llm4free version                      # Show version
llm4free text -k "python programming" # DuckDuckGo search (default)
llm4free images -k "mountains"        # Image search
llm4free news -k "AI breakthrough" -t w  # News from last week
llm4free weather -l "New York"        # Weather info
llm4free translate -k "Hola" --to en  # Translation

Supported Engines

# Use a specific engine
llm4free text -k "climate change" -e bing
llm4free text -k "quantum physics" -e wikipedia

Full CLI reference: docs/cli.md

🤖 AI Chat Providers

All providers use the OpenAI-compatible interface (client.chat.completions.create(...)).

Free Providers (No Auth Required)

from llm4free.llm.heckai import HeckAI
from llm4free.llm.artingai import ArtingAI
from llm4free.llm.freeai import FreeAI

# HeckAI - multiple models
client = HeckAI()
response = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

# ArtingAI
client = ArtingAI()
response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Hello!"}],
)

Authenticated Providers

from llm4free.llm.Auth.groq import Groq
from llm4free.llm.Auth.deepinfra import DeepInfra

groq = Groq(api_key="your-key")
response = groq.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[{"role": "user", "content": "Write a Python function to sort a list"}],
)
print(response.choices[0].message.content)

Streaming

from llm4free.llm.heckai import HeckAI

client = HeckAI()
stream = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

See llm4free/llm/ for all available provider implementations.

🔍 Search Engines

from llm4free import DuckDuckGoSearch, BingSearch, YahooSearch, BraveSearch

# DuckDuckGo
ddg = DuckDuckGoSearch()
results = ddg.text("python frameworks", max_results=5)

# Bing
bing = BingSearch()
results = bing.text("climate change solutions")

# Brave
brave = BraveSearch()
results = brave.text("machine learning tutorials")

Search docs: docs/search.md

🖼️ Text-to-Image

from llm4free.Provider.TTI import PollinationsAI, TogetherImage

# PollinationsAI
poll = PollinationsAI()
poll.generate_image(prompt="A cyberpunk city at night")

# Together AI
together = TogetherImage()
together.generate_image(prompt="A robot playing chess")

TTI docs: docs/getting-started.md#image-generation

🗣️ Text-to-Speech

from llm4free.Provider.TTS import ElevenlabsTTS, ParlerTTS

tts = ElevenlabsTTS()
tts.text_to_speech("Hello, world!", voice="alloy")

TTS model registry: docs/models.md

🌐 OpenAI-Compatible API Server

Run a local FastAPI server that serves any LLM4Free provider through standard OpenAI endpoints.

# Start the server
llm4free-server

# Custom config
llm4free-server --port 8080 --host 0.0.0.0 --debug

Use with the official OpenAI Python client

from openai import OpenAI

client = OpenAI(api_key="dummy", base_url="http://localhost:8000/v1")

response = client.chat.completions.create(
    model="ChatGPT/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Docker Deployment

docker-compose up llm4free-api
docker-compose -f docker-compose.yml -f docker-compose.no-auth.yml up llm4free-api

Full server docs: docs/openai-api-server.md | Docker: docs/DOCKER.md

🧩 Tool Calling

Built-in function calling that works with any provider.

from llm4free.llm.heckai import HeckAI
from llm4free.AIbase import Tool

def get_weather(city: str) -> str:
    return f"Weather in {city}: Sunny, 25C"

weather_tool = Tool(
    name="get_weather",
    description="Get current weather for a city.",
    parameters={"city": {"type": "string", "description": "City name."}},
    implementation=get_weather,
)

client = HeckAI(tools=[weather_tool])
response = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "What is the weather in London?"}],
)
print(response.choices[0].message.content)

Tool calling docs: docs/tool-calling.md

📊 Model Registry

Enumerate available models across all providers.

from llm4free import model

# All LLM models
all_models = model.llm.list()
print(f"Total: {len(all_models)}")

# Models by provider
summary = model.llm.summary()
for provider, count in summary.items():
    print(f"  {provider}: {count}")

# TTS voices
voices = model.tts.list()
print(f"Total voices: {len(voices)}")

Model registry docs: docs/models.md

🛠️ Developer Tools

📚 Documentation

🤝 Contributing

We welcome contributions — new providers, search engines, bug fixes, and docs. With 40+ providers and counting, there's always room to help.

1. Fork the repository
2. Create a feature branch
3. Make changes with descriptive commits
4. Submit a pull request

See docs/contributing.md for full guidelines, and docs/provider-development.md to add a provider.

📄 License

Released under Apache-2.0. See LICENSE.md. Free for personal and commercial use.