---

✨ 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

Category	Engines
text	ddg, bing, brave, yahoo, mojeek, wikipedia
images	ddg, bing, brave, yahoo
videos	ddg, brave, yahoo
news	ddg, bing, brave, yahoo
suggestions	ddg, bing, brave, yahoo
weather	ddg, yahoo
answers	ddg
translate	ddg
maps	ddg

# 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

Tool	Description	Docs
SwiftCLI	CLI framework with decorators	docs/swiftcli.md
Scout	HTML parser & web crawler	docs/scout.md
LitPrinter	Styled debug printing	docs/litprinter.md
LitAgent	User-agent rotation	docs/litagent.md
GitAPI	GitHub data extraction	docs/gitapi.md
GGUF	Model conversion & quantization	docs/gguf.md
ZeroArt	ASCII art generator	docs/zeroart.md
Weather	Weather toolkit	docs/weather.md
Decorators	@timeIt and @retry	docs/decorators.md
Sanitize	Stream sanitization	docs/sanitize.md
Prompts	System prompt manager	docs/awesome-prompts.md

---

📚 Documentation

Resource	Description
Getting Started	Installation, first chat, web search, image generation
Architecture	System design, layers, and data flows
CLI Reference	All CLI commands and options
Python Client	Unified client with auto-failover
API Server	OpenAI-compatible FastAPI server
Model Registry	Enumerate LLM, TTS, TTI models
Tool Calling	Function calling with any provider
Search Docs	Multi-engine search API
Scout	HTML parser and crawler
Provider Development	Create custom providers
Deployment	Production deployment guide
Docker	Docker setup and compose profiles
Inferno	Local LLM server
Troubleshooting	Common issues and solutions
Contributing	How to contribute
Provider Modules	All provider implementations
Docs Hub	Full documentation index

---

🤝 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.

---