LLM4Free: one Python client for 40+ chat providers, search, images and voice

The problem LLM4Free solves, and who actually needs it

Calling several AI providers from one Python program normally means several SDKs, several authentication styles, and several response shapes. LLM4Free's answer is to make every chat provider implement the same method signature as the OpenAI Python SDK. The README states that every chat provider implements client.chat.completions.create(...), so switching backends is a one-line change rather than a rewrite. On top of that, the project bundles web search across DuckDuckGo, Bing, Brave, Yahoo, Mojeek and Wikipedia, text-to-image providers such as Pollinations, Together and Stable Horde, text-to-speech providers such as ElevenLabs, OpenAI FM, Qwen and Murf, plus utilities including a crawler named Scout, a GitHub data toolkit, temp-mail, GGUF conversion and user-agent rotation.

The audience is developers who want to try many models quickly and do not want to register for an API key before writing the first line. The README calls out HeckAI and Pollinations as usable with zero API key, with the option to graduate to Groq, DeepInfra or your own key later. If you are building a product with a contractual uptime requirement, the free tier is not what you want; if you are exploring, comparing outputs, or wiring an internal tool, the breadth is the point. The package requires Python 3.10 or newer according to pyproject.toml, and it is published on PyPI as llm4free.

How the unified Client resolves a provider and fails over

The mechanism is a dispatcher, not a new inference stack. You construct Client from llm4free.client, and the client decides which backend answers. Passing model="auto" lets it resolve a working provider and model; passing model="Provider/Model", for example "HeckAI/google/gemini-2.5-flash-preview", forces a specific backend. The README states that the unified Client retries across providers, which is the auto-failover behaviour, and that client.chat.completions.last_provider reports which provider served the request. Setting print_provider_info=True prints that information live, which is the practical way to find out what actually handled a call.

The same object covers images through client.images.generate(...), with client.images.create(...) as an alias, and accepts model="auto" there too. Responses are shaped like OpenAI responses, so response.choices[0].message.content and image.data[0].url are the fields you read. Two things are worth noting. First, auto-failover hides which endpoint failed, so a pipeline that silently degrades from a strong model to a weak one looks identical to a healthy one unless you log last_provider. Second, the project also exposes raw providers such as HeckAI from llm4free.llm.heckai; the README recommends the unified Client because the raw classes skip model resolution and failover.

Installing LLM4Free and making a first call

The README gives three installation paths. The simplest is pip, with an extra for the API server and another for development tooling. The extra names are api and dev; do not invent others.

pip install -U llm4free
pip install -U "llm4free[api]"
pip install -U "llm4free[dev]"

The project also documents uv, including running the CLI without a permanent install, and a Docker image. The Docker path is useful if you only want the server rather than the library.

uv add llm4free
uv run llm4free --help
uv tool install llm4free

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

For a first real call, the README's quick start uses the unified client with model="auto". The response object mirrors the OpenAI SDK, so the content sits at response.choices[0].message.content.

from llm4free.client import Client

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)

Web search uses a separate class rather than the chat client. DuckDuckGoSearch().text(...) returns a list of dictionaries with title and href keys, which is the shape the README's loop prints.

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']}")

If you want the OpenAI-compatible server instead of the library, install the api extra and use docker-compose.yml, which sets LLM4FREE_HOST=0.0.0.0, LLM4FREE_PORT=8000 and LLM4FREE_WORKERS=1. The compose file's own comment states that authentication is currently disabled by default in the server, and that the authentication and rate limiting settings may not be fully supported yet. Treat that as a deployment constraint, not a footnote.

Where LLM4Free breaks: reverse-engineered providers and a default-open server

The free tier is the selling point and the main risk. Providers such as HeckAI and Pollinations are reached without an API key, and the repository's own topic list includes reverse-engineering. That means the integration depends on endpoints the project does not control and has no agreement with. When such an endpoint changes its request format, adds a challenge, or blocks a client, the provider stops working, and your only recourse is to wait for a release or switch models. The auto-failover in the unified Client softens this, but it converts a hard failure into a silent substitution, which is worse for anything that needs reproducible output.

The API server has its own sharp edge. The docker-compose.yml comments say authentication is currently disabled by default and that authentication and rate limiting settings may not be fully supported by the server yet. Exposing that container on a public interface hands an open proxy to anyone who finds it. The environment variables LLM4FREE_CORS_ORIGIN and LLM4FREE_REQUEST_LOGGING exist, but no supported auth story is documented, so there is nothing to configure your way out of.

Finally, the scope is wide. Search, chat, images, speech, temp-mail, GGUF conversion and a crawler in one distribution means a large dependency surface and many code paths that can each break independently. If you only need one provider, the OpenAI SDK plus that provider's own client is a smaller thing to maintain.

LLM4Free versus LiteLLM: dispatcher against gateway

LiteLLM is the closest comparison, and the difference is architectural rather than cosmetic. LiteLLM normalises many providers behind one interface by translating each provider's official API into a common format; it assumes you hold API keys and that the upstream APIs are documented and stable. LLM4Free instead mixes official-key providers with keyless, reverse-engineered ones, and adds non-LLM utilities that LiteLLM does not attempt: multi-engine web search, text-to-image, text-to-speech, temp-mail and a GitHub data toolkit.

The trade-off follows from that. LiteLLM's behaviour is predictable because the contracts it targets are published; LLM4Free's breadth comes from endpoints with no contract at all. If your goal is a routing layer in front of paid APIs you already pay for, LiteLLM is the safer shape. If your goal is to reach models and utilities you have no key for, in one import, LLM4Free is doing something LiteLLM does not offer. The two are not substitutes so much as answers to different questions, and the honest test is whether you can tolerate a backend disappearing between releases.

Maintenance, release cadence and what Apache-2.0 covers

The repository is not archived, and the last push was on 2026-09-14, the same day as the v2026.9.14 release. The two preceding releases, v2026.9.8 and v2026.9.7, landed within the same week, so the project is moving quickly. A fast cadence is what you want from a package built on reverse-engineered endpoints, since fixes have to ship when a provider changes. It also means version numbers move often, and the Dockerfile's build argument LLM4FREE_VERSION defaults to latest, so an image built today and one built next month are not the same artifact. Pin the version if you need reproducibility.

The licence is Apache-2.0, stated in pyproject.toml as license = {text = "Apache-2.0"} and shown in the README badge. That permits commercial use and modification under the usual Apache terms, including attribution and the patent grant. Two separate files, LICENSE and LICENSE.md, sit at the repository root, and the README also links a LEGAL_NOTICE.md. What those notices say is not documented in the README, and they may add conditions the licence alone does not describe. Read them before shipping; this is a description of the licence identifier, not legal advice.

Editorial conclusion

LLM4Free fits prototyping, scripts and internal tooling where you want many backends without writing per-provider glue, and it is Apache-2.0 so commercial use is permitted. It does not fit production systems that require a provider SLA, because many of the free backends are reverse-engineered and can break without notice. Before adopting it, verify the current provider list, whether the API server's authentication is enabled in the version you install, and whether the free tiers you plan to use still answer.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. OEvortex/llm4free on GitHub
3. Project website
4. README
5. Releases