GPT4Free (g4f) is a community-driven project that aggregates multiple accessible providers and interfaces to make working with modern LLMs and media-generation models easier and more flexible. The system functions as a multi-provider router and abstraction layer, enabling applications to interact with dozens of AI services through a single API. The project provides OpenAI-compatible interfaces, automatic provider failover, and handles provider-specific authentication requirements like HAR files and browser automation.
The system is designed to:
Sources: README.md29-32 README.md74-82 g4f/__init__.py27-118
| Feature | Description | Implementation |
|---|---|---|
| Multi-Provider Aggregation | Integrates 40+ AI service providers | g4f/Provider/__init__.py9-265 |
| Automatic Model Registry | Registry for discovery and alias resolution | g4f/models.py9-67 |
| Provider Routing | Intelligent selection based on model and capability | g4f/client/service.py17-18 |
| Failover & Retry | Automatic provider rotation on failure | g4f/Provider/__init__.py4-6 |
| OpenAI Compatibility | FastAPI server mimics OpenAI API structure | setup.py82 |
| Authentication Management | HAR files, cookies, and browser automation | g4f/cookies.py1-13 g4f/Provider/needs_auth/__init__.py1-45 |
| Streaming Support | Async generators for streaming responses | g4f/__init__.py65-118 |
| Media Generation | Image, audio, video generation capabilities | g4f/models.py101-115 |
| Multiple Interfaces | Python clients, HTTP API, web GUI, CLI, MCP | setup.py124-130 |
| Docker Deployment | Full and slim images with persistent storage | README.md106-144 |
Sources: README.md74-82 g4f/models.py9-115 g4f/Provider/__init__.py9-265
The following diagram maps the major system components to their code implementations:
Architecture Notes:
setup.py provide CLI commands like g4f and g4f-mcp setup.py124-130Client and asynchronous AsyncClient classes provide the primary user interface g4f/client/__init__.py10ModelRegistry maintains the model catalog g4f/models.py9-67 while get_model_and_provider performs routing g4f/client/service.py17Sources: g4f/__init__.py27-118 g4f/models.py9-115 g4f/Provider/__init__.py1-265 setup.py124-130
The ModelRegistry class provides automatic model discovery and registration:
Key Methods:
ModelRegistry.register(model, aliases) - Registers a model and optional aliases g4f/models.py15-23ModelRegistry.get(name) - Retrieves model by name or alias g4f/models.py25-31Model.__post_init__() - Auto-registers model after dataclass initialization g4f/models.py90-93Model Types:
Model - Base text generation model g4f/models.py71-84ImageModel - Image generation models g4f/models.py101-102AudioModel - Audio processing models g4f/models.py105-106VideoModel - Video generation models g4f/models.py109-110VisionModel - Vision-capable models g4f/models.py113-114Sources: g4f/models.py9-115
The provider hierarchy implements the abstraction layer:
| Base Class | Purpose | Key Methods | File Location |
|---|---|---|---|
BaseProvider | Interface definition | working, url | g4f/Provider/__init__.py3 |
AsyncGeneratorProvider | Async streaming base | create_async_generator | g4f/Provider/__init__.py5 |
IterListProvider | Failover list | Iterates through providers | g4f/Provider/__init__.py4 |
RetryProvider | Retry logic | Handles retries across providers | g4f/Provider/__init__.py4 |
Provider Categories:
g4f/Provider/needs_auth/): Require API keys, cookies, or tokens g4f/Provider/__init__.py15-265g4f/Provider/): No authentication required (e.g., DeepInfra, Cloudflare) g4f/Provider/__init__.py67-103Ollama g4f/Provider/__init__.py217Sources: g4f/Provider/__init__.py1-265
The following sequence diagram shows the request flow from client to provider:
Key Steps:
ChatCompletion._prepare_request() normalizes parameters and resolves images into the media kwarg g4f/__init__.py29-62get_model_and_provider() resolves model strings to Model objects and selects the best provider g4f/client/service.py17ModelRegistry.get() retrieves the model configuration including its best_provider g4f/models.py25-31Sources: g4f/__init__.py27-118 g4f/models.py25-31 g4f/client/service.py17
Each Model instance contains:
name (str): Canonical model identifier.base_provider (str): Provider organization name.best_provider (ProviderType): The preferred provider, often an IterListProvider for failover g4f/models.py71-84Example:
Providers implement the BaseProvider interface. Many use IterListProvider to wrap multiple sources for a single model name, providing automatic fallback if the first provider in the list is unavailable g4f/models.py118-135
Sources: g4f/models.py71-161 g4f/Provider/__init__.py1-265
| Interface | Entry Point | Purpose |
|---|---|---|
| Python Client | g4f.client.Client | Direct library usage in Python apps g4f/__init__.py10 |
| CLI | g4f command | Command-line interaction setup.py126 |
| Web GUI | g4f.gui | Flask-based browser interface setup.py83-88 |
| Interference API | g4f.api | OpenAI-compatible FastAPI server setup.py82 |
| MCP Server | g4f-mcp command | Model Context Protocol for tool integration setup.py127 |
Docker Deployment:
hlohaus789/g4f:latest includes browser automation README.md116-124hlohaus789/g4f:latest-slim for lightweight environments README.md130-140Sources: README.md106-144 setup.py124-130
The package uses a modular dependency system:
Core Dependencies (setup.py12-18):
requests, aiohttp, brotli, pycryptodome, nest-asyncio2.
Optional Extras:
g4f[all]: Full installation including browser automation and all providers setup.py21-47g4f[slim]: Optimized for size, including essential API and GUI components setup.py48-70g4f[api]: FastAPI and Uvicorn for server deployments setup.py82g4f[gui]: Flask and UI dependencies setup.py83-88Sources: setup.py12-104
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.