# What Is ClientFactory in gpt4free? Factory Pattern Implementation Guide

> Discover how ClientFactory in gpt4free simplifies creating synchronous and asynchronous client instances. Learn about provider configuration, resolution, and caching.

- Repository: [Tekky/gpt4free](https://github.com/xtekky/gpt4free)
- Tags: deep-dive
- Published: 2026-03-04

---

**ClientFactory in gpt4free is a central factory class that abstracts the complexity of constructing synchronous `Client` and asynchronous `AsyncClient` instances with correct provider configurations, handling provider resolution, custom endpoints, and live provider caching automatically.**

The `ClientFactory` class, defined in [`g4f/client/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/__init__.py), serves as the primary entry point for the gpt4free library. By implementing the factory pattern, it encapsulates the intricate logic of provider discovery, instantiation, and client wiring, allowing developers to create fully configured clients using simple string identifiers or custom configurations without managing provider internals directly.

## Why gpt4free Uses a Client Factory

### The Problem: Provider Configuration Complexity

The gpt4free library supports dozens of AI providers, each with different initialization requirements. Users can specify providers in multiple ways—by literal name (e.g., `"PollinationsAI"`), by custom provider classes, or through live provider definitions fetched from a remote registry. Additionally, users may need custom API endpoints, separate media providers for image generation, or specific proxy configurations.

### The Solution: Centralized Factory Pattern

`ClientFactory` solves these challenges through a unified interface. The following table illustrates how the factory handles specific configuration concerns:

| Concern | How `ClientFactory` Solves It |
|---|---|
| **Multiple provider specification formats** – literal names, custom classes, or live registry definitions. | Accepts any form via `create_provider` and internally resolves to a concrete `BaseProvider` subclass. |
| **Custom API endpoints** – pointing clients at arbitrary OpenAI-compatible endpoints. | When `provider="custom"` or `custom:<id>` is specified, builds a provider on-the-fly via `create_custom_provider`. |
| **Separate media providers** – using different backends for chat completions vs. image generation. | `create_client` and `create_async_client` accept an optional `media_provider` argument forwarded directly to the underlying client. |
| **Proxy and authentication** – passing API keys, proxies, or extra parameters. | Forwards any additional `**kwargs` straight to the client constructor, becoming part of the provider instance. |
| **Live provider caching** – avoiding repeated downloads of the remote provider registry. | Downloads `https://g4f.dev/dist/js/providers.json` on first use, caches it in the cookies directory, and reuses it for subsequent calls. |

## Core Implementation of ClientFactory

### Provider Resolution Logic

The `create_provider` classmethod (lines 99-151 in [`g4f/client/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/__init__.py)) serves as the core resolution engine. It handles three distinct input types:

1. **String identifiers** – Looks up the provider in the live registry or built-in providers
2. **Provider classes** – Validates and returns the class directly
3. **Custom endpoint specifications** – Constructs ephemeral provider classes for OpenAI-compatible endpoints

```python

# g4f/client/__init__.py

class ClientFactory:
    _live_providers_url = "https://g4f.dev/dist/js/providers.json"
    _live_providers: Dict[str, Dict] = {}

    @classmethod
    def create_provider(
        cls,
        name: str,
        provider: Union[Type[BaseProvider], str],
        base_url: str = None,
        api_key: str = None,
        **kwargs
    ) -> Type[BaseProvider]:
        # Handles custom providers, live providers, or direct class objects

        ...

```

### Live Provider Caching

The factory maintains a class-level cache `_live_providers` that stores the remote registry. When `create_provider` encounters a string identifier not found in built-in providers, it lazily loads the JSON from `https://g4f.dev/dist/js/providers.json`, caches it to the user's cookies directory, and performs the lookup against the live list.

### Client Construction Methods

The public API consists of two factory methods:

- **`create_client`** (lines 88-95) – Returns a synchronous `Client` instance
- **`create_async_client`** (lines 31-38) – Returns an asynchronous `AsyncClient` instance

Both methods follow the same pattern: resolve the provider using `create_provider`, then instantiate the appropriate client class with the resolved provider and any additional configuration:

```python
return Client(
    provider=cls.create_provider(None, provider, base_url, api_key, **kwargs),
    media_provider=media_provider,
    api_key=api_key,
    base_url=base_url,
    proxies=proxies,
    **kwargs
)

```

## Practical Code Examples

### 1. Create a Client with a Named Provider

Use a built-in provider name to quickly instantiate a client for specific AI services:

```python
from g4f import ClientFactory

# PollinationsAI is a built-in provider name

client = ClientFactory.create_client("PollinationsAI")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Say hello"}]
)
print(response)

```

### 2. Create an Asynchronous Client

For non-blocking I/O operations, use `create_async_client` to obtain an `AsyncClient`:

```python
from g4f import ClientFactory

async_client = ClientFactory.create_async_client("DeepInfra")

async def ask():
    resp = await async_client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "What is the time?"}]
    )
    print(resp)

# Run with asyncio.run(ask())

```

### 3. Use a Custom OpenAI-Compatible Endpoint

Point the client at any OpenAI-compatible API by specifying `base_url` and `api_key`:

```python
from g4f import ClientFactory

custom_client = ClientFactory.create_client(
    base_url="https://api.openai.com/v1",
    api_key="sk-XXXXXXXXXXXXXXXX"
)

# Now any model supported by the endpoint can be used

resp = custom_client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Translate to French"}]
)
print(resp)

```

### 4. Separate Media Provider for Image Generation

Configure different backends for chat completions and image generation using the `media_provider` parameter:

```python
from g4f import ClientFactory

client = ClientFactory.create_client(
    provider="PollinationsAI",
    media_provider="StableDiffusion"
)

img_resp = client.images.generate(
    prompt="a futuristic city at sunset",
    model="stable-diffusion-xl"
)
print(img_resp)

```

## Key Files in the Client Architecture

Understanding the `ClientFactory` requires familiarity with these source files:

| File | Role |
|------|------|
| [`g4f/client/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/__init__.py) | Defines `ClientFactory`, the provider resolution logic, and the `create_client` / `create_async_client` entry points. |
| [`g4f/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/__init__.py) | Public API surface that re-exports `ClientFactory`, `Client`, `AsyncClient`, and helper utilities. |
| [`g4f/client/models.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/models.py) | Contains `ClientModels` helper used by `Client` and `AsyncClient` for model management. |
| [`g4f/providers/types.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/types.py) | Declares the `BaseProvider` abstract class and `ProviderType` alias used throughout the factory. |
| [`g4f/client/service.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/service.py) | Provides `convert_to_provider` and other runtime helpers that the factory leverages when interpreting string provider names. |

These files collectively implement the abstraction that lets developers work with a single, intuitive API (`ClientFactory.create_client(...)`) while the library manages provider discovery, registration, and client wiring behind the scenes.

## Summary

- **ClientFactory in gpt4free** acts as a centralized factory that eliminates boilerplate when constructing `Client` and `AsyncClient` instances.
- It resolves multiple provider specification formats—string names, custom classes, or live registry entries—into concrete `BaseProvider` subclasses via `create_provider`.
- The factory caches the live provider list from `https://g4f.dev/dist/js/providers.json` to avoid repeated network requests.
- It supports custom OpenAI-compatible endpoints, separate media providers for image generation, and passes through authentication and proxy parameters transparently.
- Entry points `create_client` and `create_async_client` in [`g4f/client/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/__init__.py) provide the public interface used by most library consumers.

## Frequently Asked Questions

### What is the difference between ClientFactory.create_client and ClientFactory.create_async_client?

`create_client` returns a synchronous `Client` instance suitable for standard blocking I/O operations, while `create_async_client` returns an `AsyncClient` designed for asynchronous programming with `async`/`await` syntax. Both methods use the same `create_provider` logic internally, but instantiate different client classes optimized for their respective concurrency models.

### How does ClientFactory handle custom OpenAI-compatible endpoints?

When you pass a `base_url` parameter without a specific provider name, or use the `provider="custom"` argument, `ClientFactory` invokes `create_custom_provider` to build an ephemeral provider class on-the-fly. This dynamically constructed provider points to your specified endpoint and accepts your API key, allowing seamless integration with any OpenAI-compatible API without requiring pre-defined provider classes.

### Where does ClientFactory store the cached provider list?

The factory downloads the live provider registry from `https://g4f.dev/dist/js/providers.json` and caches it in the user's cookies directory (typically under the system's temporary or application data folder). This cache persists across sessions, minimizing network overhead while ensuring the provider list remains relatively fresh for subsequent client instantiations.

### Can I use different providers for chat and image generation with ClientFactory?

Yes, the `create_client` and `create_async_client` methods accept an optional `media_provider` parameter that accepts the same variety of inputs as the main `provider` argument. When specified, this separate provider handles image generation operations via `client.images.generate()`, while the primary provider manages chat completions, enabling hybrid workflows that leverage specialized services for different media types.