gpt4free

https://github.com/xtekky/gpt4free
Admin
GPT4Free is an open-source project that provides free access to various AI models, advocating for...
Tokens:23,305
Snippets:236
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install GPT4Free using pip

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Recommended installation method using pip. Installs the g4f package with all optional extras for full functionality.

```bash
pip install -U g4f[all]
```

--------------------------------

### Install g4f Python Library

Source: https://context7.com/xtekky/gpt4free/llms.txt

Install the g4f library with optional dependencies for full functionality, or a minimal version. Installation from source is also supported.

```bash
# Full install (all optional dependencies)
pip install -U g4f[all]

# Minimal install
pip install g4f

# From source
git clone https://github.com/xtekky/gpt4free.git
cd g4f
pip install -e .
```

--------------------------------

### Install GPT4Free from Source

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Installs GPT4Free by cloning the repository and using pip. This method is useful for development or if you need to modify the source code.

```bash
git clone https://github.com/xtekky/gpt4free.git
cd gpt4free
pip install -r requirements.txt
pip install -e .
```

--------------------------------

### Install Dependencies

Source: https://github.com/xtekky/gpt4free/blob/main/SKILL.md

Install required Python dependencies for gpt4free.

```bash
pip install -r requirements.txt
```

--------------------------------

### Run GPT4Free GUI

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Launches the graphical user interface for GPT4Free. Ensure the g4f library is installed.

```python
python -c "from g4f.gui import run_gui; run_gui()"
```

--------------------------------

### JavaScript Browser Client Example

Source: https://context7.com/xtekky/gpt4free/llms.txt

Integrate g4f directly from a browser using the official CDN-hosted JavaScript client. This example demonstrates making a chat completion request.

```html
<!DOCTYPE html>
<html>
<body>
<script type="module">
  import Client from 'https://g4f.dev/dist/js/client.js';

  const client = new Client();
  const result = await client.chat.completions.create({
    model: 'gpt-4.1',
    messages: [{ role: 'user', content: 'Explain quantum computing in one sentence.' }]
  });
  document.body.innerText = result.choices[0].message.content;
</script>
</body>
</html>
```

--------------------------------

### Run GPT4Free GUI from CLI

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Starts the GPT4Free web client using the command-line interface. Specify the port and enable debug mode if needed.

```bash
python -m g4f.cli gui --port 8080 --debug
```

--------------------------------

### Start gpt4free API Server

Source: https://github.com/xtekky/gpt4free/blob/main/SKILL.md

Start the gpt4free API server on the default port 8080. Alternatively, use the `api` command with debug mode.

```bash
python -m g4f --port 8080
```

```bash
g4f api --debug --port 8080
```

--------------------------------

### Synchronous Text Generation with GPT4Free Python Client

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Demonstrates how to use the synchronous client to generate text. Ensure the 'g4f' library is installed.

```python
import g4f

response = g4f.ChatCompletion.create(
    model=g4f.models.default,
    messages=[{"role": "user", "content": "Hello world"}],
    provider=g4f.Provider.Bing
)
print(response)
```

--------------------------------

### Install g4f Requirements for aarch64

Source: https://github.com/xtekky/gpt4free/blob/main/docs/aarch64-compatibility.md

Install the minimum requirements for basic functionality or the full requirements which may need compilation on aarch64.

```bash
pip install -r requirements-min.txt
```

```bash
pip install -r requirements.txt
```

--------------------------------

### Launch Web GUI

Source: https://context7.com/xtekky/gpt4free/llms.txt

Start the integrated web-based chat UI using the run_gui function. Specify host and port, and enable debug mode if needed.

```python
from g4f.gui import run_gui
run_gui(host="0.0.0.0", port=8080, debug=True)
```

--------------------------------

### Start GPT4Free MCP Server (stdio mode)

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Initiates the Model Context Protocol (MCP) server using either the 'g4f' command or the Python module. This mode uses standard input/output for communication.

```bash
# Using g4f command
g4f mcp

# Or using Python module
python -m g4f.mcp
```

--------------------------------

### Test g4f Installation on aarch64

Source: https://github.com/xtekky/gpt4free/blob/main/docs/aarch64-compatibility.md

Verify that g4f can be imported successfully and that the command-line interface is functional.

```python
# Test basic import
from g4f.client import Client
client = Client()
print("✓ g4f imported successfully")
```

```python
# Test CLI
import subprocess
result = subprocess.run(['g4f', '--help'], capture_output=True)
print("✓ CLI works" if result.returncode == 0 else "✗ CLI issues")
```

--------------------------------

### Start GPT4Free MCP Server (HTTP mode)

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Starts the MCP server in HTTP mode, providing JSON-RPC and health check endpoints. You can customize the host and port for the server.

```bash
# Start HTTP server on port 8765
g4f mcp --http --port 8765

# Custom host and port
g4f mcp --http --host 127.0.0.1 --port 3000
```

--------------------------------

### Run GPT4Free GUI from Python

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Launches the GPT4Free web-based GUI directly from a Python script. Ensure you have the g4f package installed.

```python
from g4f.gui import run_gui
run_gui()
```

--------------------------------

### Run MCP Server in stdio Mode

Source: https://context7.com/xtekky/gpt4free/llms.txt

Start the Model Context Protocol (MCP) server in stdio mode for integration with AI assistants like Claude Desktop.

```bash
python -m g4f.mcp
```

--------------------------------

### Start GPT4Free FastAPI Server

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Launches the FastAPI server for the Interference API. This allows programmatic access to GPT4Free functionalities. Debug mode is optional.

```bash
python -m g4f --port 8080 --debug
```

--------------------------------

### Install PyYAML for g4f

Source: https://github.com/xtekky/gpt4free/blob/main/docs/config-yaml-routing.md

Ensure PyYAML is installed for g4f to load YAML configuration files. It's included in the main requirements.

```bash
pip install pyyaml
```

--------------------------------

### Python Client Image Generation

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Example of generating an image using the GPT4Free client. This pattern is used for AI-powered image creation.

```python
client.images.generate(...)
```

--------------------------------

### AsyncImages Generate

Source: https://context7.com/xtekky/gpt4free/llms.txt

Provides an example of asynchronous image generation using the AsyncClient.

```APIDOC
## `AsyncImages.generate` — Async image generation

Async variant of `Images.generate`, used with `AsyncClient`.

```python
import asyncio
from g4f.client import AsyncClient

async def main():
    client = AsyncClient()
    response = await client.images.generate(
        model="flux",
        prompt="photorealistic mountain landscape at dawn",
        response_format="url"
    )
    for image in response.data:
        print(f"URL: {image.url}  |  Prompt: {image.revised_prompt}")

asyncio.run(main())
```
```

--------------------------------

### Python Client Chat Completion

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Example of creating a chat completion using the GPT4Free client. This is a common pattern for text generation tasks.

```python
client.chat.completions.create(...)
```

--------------------------------

### Get Specific Provider Details

Source: https://context7.com/xtekky/gpt4free/llms.txt

Obtain detailed information about a specific provider, including supported models and flags, by querying /v1/providers/{provider}.

```bash
curl http://localhost:1337/v1/providers/PollinationsAI | python -m json.tool
```

--------------------------------

### Check g4f Version

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use the VersionUtils to check the current installed g4f version against PyPI or GitHub releases. It can also print an update notice.

```python
from g4f.version import utils

# Current installed version
print(utils.current_version)    # e.g. "0.4.2.0"

# Latest available version on PyPI
print(utils.latest_version)     # e.g. "0.4.3.1"

# Print update notice and return bool
is_current = utils.check_version()
# "New g4f version available: 0.4.3.1 (current: 0.4.2.0) | pip install -U g4f"
```

--------------------------------

### Streaming Response Example (OpenAI Compatible)

Source: https://github.com/xtekky/gpt4free/blob/main/docs/reasoning-standardization.md

This JSON structure represents a streaming chat completion response, adhering to the OpenAI format with the 'reasoning' field in the delta.

```json
{
  "id": "chatcmpl-example",
  "object": "chat.completion.chunk",
  "choices": [{
    "index": 0,
    "delta": {
      "role": "assistant",
      "reasoning": "I need to think about this step by step..."
    },
    "finish_reason": null
  }]
}
```

--------------------------------

### Synchronous Image Generation with gpt4free

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use `Client.images.generate` for synchronous image generation. The default behavior saves images locally and returns a local URL. Specify `response_format` to get remote URLs or base64-encoded data.

```python
from g4f.client import Client

client = Client()

# Default: saves to local media directory, returns local URL
response = client.images.generate(
    model="flux",
    prompt="a white siamese cat sitting on a windowsill at sunset"
)
print(response.data[0].url)        # /media/<filename>.png
print(response.data[0].revised_prompt)

# Return original remote URL without local download
response_url = client.images.generate(
    model="flux",
    prompt="futuristic cityscape",
    response_format="url"
)
print(response_url.data[0].url)    # https://...

# Return base64-encoded image data
response_b64 = client.images.generate(
    model="flux",
    prompt="abstract geometric art",
    response_format="b64_json"
)
print(response_b64.data[0].b64_json[:40])  # iVBORw0KGgo...
```

--------------------------------

### Run g4f Docker Container (Full Image)

Source: https://context7.com/xtekky/gpt4free/llms.txt

Deploy the g4f application using Docker with a full image, including VNC desktop for provider logins. Mount volumes for persistent storage.

```bash
mkdir -p har_and_cookies generated_media
sudo chown -R 1200:1201 har_and_cookies generated_media

docker run -p 8080:8080 -p 7900:7900 --shm-size="2g" \
  -v ${PWD}/har_and_cookies:/app/har_and_cookies \
  -v ${PWD}/generated_media:/app/generated_media \
  hlohaus789/g4f:latest
```

--------------------------------

### Run GPT4Free with Docker (Slim)

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Deploys a slim version of GPT4Free using Docker. This version uses different port mappings and mounts volumes for data persistence.

```bash
docker run -p 1337:8080 -p 8080:8080 \
  -v ${PWD}/har_and_cookies:/app/har_and_cookies \
  -v ${PWD}/generated_media:/app/generated_media \
  hlohaus789/g4f:latest-slim
```

--------------------------------

### Provider Information

Source: https://context7.com/xtekky/gpt4free/llms.txt

Enumerate active providers or get detailed information about a specific one.

```APIDOC
## GET /v1/providers and GET /v1/providers/{provider}

### Description
Enumerate active providers or get detailed information about a specific one.

### Method
GET

### Endpoint
/v1/providers
/v1/providers/{provider}

### Parameters
#### Path Parameters
- **provider** (string) - Optional - The name of the specific provider to get details for.

### Response
#### Success Response (200)
- **List of providers** (array of strings) - When requesting `/v1/providers`.
- **Provider details** (object) - When requesting `/v1/providers/{provider}`.
  - **id** (string) - The provider's unique identifier.
  - **url** (string) - The provider's URL.
  - **models** (array of strings) - List of supported models.
  - **image_models** (array of strings) - List of supported image generation models.
  - **vision_models** (array of strings) - List of supported vision models.
  - **params** (array) - Provider-specific parameters.

### Response Example (Provider Detail)
```json
{
  "id": "PollinationsAI",
  "url": "https://pollinations.ai",
  "models": ["openai-large", "openai", ...],
  "image_models": ["flux", "flux-realism", ...],
  "vision_models": ["openai-large"],
  "params": [...] 
}
```
```

--------------------------------

### Run Slim Docker Image for GPT4Free

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

This command uses a slim Docker image, suitable for x64 and arm64 architectures. It maps ports and volumes, and the slim image can update packages on startup.

```bash
mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media
chown -R 1000:1000 ${PWD}/har_and_cookies ${PWD}/generated_media

docker run \
  -p 1337:8080 -p 8080:8080 \
  -v ${PWD}/har_and_cookies:/app/har_and_cookies \
  -v ${PWD}/generated_media:/app/generated_media \
  hlohaus789/g4f:latest-slim
```

--------------------------------

### Interference REST API — `GET /v1/models`

Source: https://context7.com/xtekky/gpt4free/llms.txt

Returns all available models and providers in OpenAI format.

```APIDOC
## Interference REST API — `GET /v1/models`

Returns all available models and providers in OpenAI format.

```bash
curl http://localhost:1337/v1/models | python -m json.tool
# {
#   "object": "list",
#   "data": [
#     {"id": "gpt-4o", "object": "model", "created": 0, "owned_by": "", "image": false, "vision": true},
#     {"id": "flux",   "object": "model", "created": 0, "owned_by": "", "image": true,  "vision": false},
#     ...
#   ]
# }

# Models for a specific provider
curl http://localhost:1337/api/PollinationsAI/models | python -m json.tool
```
```

--------------------------------

### Audio Generation and Transcription

Source: https://context7.com/xtekky/gpt4free/llms.txt

Demonstrates how to use the AsyncClient for text-to-speech generation (saving as MP3) and audio transcription from a WAV file.

```APIDOC
## Audio generation and transcription

Generate speech from text or transcribe audio files using the `AsyncClient`.

```python
import asyncio
from g4f.client import AsyncClient
import g4f.Provider

async def main():
    client = AsyncClient(provider=g4f.Provider.PollinationsAI)

    # Text-to-speech: generates an MP3 file
    tts = await client.chat.completions.create(
        model="openai-audio",
        messages=[{"role": "user", "content": "Say good day to the world"}],
        audio={"voice": "alloy", "format": "mp3"},
    )
    tts.choices[0].message.save("alloy.mp3")

    # Audio transcription
    with open("recording.wav", "rb") as audio_file:
        transcript = await client.chat.completions.create(
            messages="Transcribe this audio",
            provider=g4f.Provider.Microsoft_Phi_4,
            media=[[audio_file, "recording.wav"]],
            modalities=["text"],
        )
        print(transcript.choices[0].message.content)

asyncio.run(main())
```
```

--------------------------------

### Video Generation

Source: https://context7.com/xtekky/gpt4free/llms.txt

Shows how to generate video clips using HuggingFace media models via the `Client`. Includes listing available models and generating a video from a prompt.

```APIDOC
## Video generation

Generate video clips via HuggingFace media models.

```python
import g4f.Provider
from g4f.client import Client

client = Client(
    provider=g4f.Provider.HuggingFaceMedia,
    api_key="hf_your_token_here"
)

# List available video models
video_models = client.models.get_video()
print(video_models)

# Generate a video
result = client.media.generate(
    model=video_models[0],
    prompt="A time-lapse of flowers blooming in spring.",
    response_format="url"
)
print(result.data[0].url)
```
```

--------------------------------

### Basic config.yaml Structure

Source: https://github.com/xtekky/gpt4free/blob/main/docs/config-yaml-routing.md

Define custom model routes with a list of providers and their configurations.

```yaml
models:
  - name: "<model-name>"          # the name clients use
    providers:
      - provider: "<ProviderName>"  # g4f provider class name
        model: "<provider-model>"   # model name passed to that provider
        condition: "<expression>"   # optional – see below
      - provider: "..."             # fallback provider (no condition = always eligible)
        model: "..."
```

--------------------------------

### Non-streaming Response Example

Source: https://github.com/xtekky/gpt4free/blob/main/docs/reasoning-standardization.md

This JSON structure illustrates a non-streaming chat completion response, including the 'reasoning' field within the message object.

```json
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Here's my answer",
      "reasoning": "My reasoning process was..."
    }
  }]
}
```

--------------------------------

### Configure Claude Desktop with GPT4Free MCP Server

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

This JSON configuration snippet shows how to integrate GPT4Free's MCP server with Claude Desktop. It specifies the command and arguments to run the server.

```json
{
  "mcpServers": {
    "gpt4free": {
      "command": "python",
      "args": ["-m", "g4f.mcp"]
    }
  }
}
```

--------------------------------

### Interference REST API: GET /v1/models

Source: https://context7.com/xtekky/gpt4free/llms.txt

Retrieve all available models and providers in OpenAI format. You can also query models for a specific provider.

```bash
# Models for a specific provider
curl http://localhost:1337/api/PollinationsAI/models | python -m json.tool
```

--------------------------------

### ClientFactory - Provider-aware client factory

Source: https://context7.com/xtekky/gpt4free/llms.txt

Explains how to use `ClientFactory` to create pre-configured `Client` or `AsyncClient` instances using named providers, custom base URLs, or the live provider registry.

```APIDOC
## `ClientFactory` — Provider-aware client factory

Creates pre-configured `Client` or `AsyncClient` instances by named provider, custom `base_url`, or live provider registry.

```python
from g4f.client import ClientFactory

# Named provider
client = ClientFactory.create_client("PollinationsAI")
response = client.chat.completions.create(
    model="openai-large",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Custom OpenAI-compatible endpoint (e.g. a local LM Studio server)
client = ClientFactory.create_client(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio"
)
response = client.chat.completions.create(
    model="lmstudio-community/Meta-Llama-3-8B-Instruct-GGUF",
    messages=[{"role": "user", "content": "What is 2+2?"}]
)
print(response.choices[0].message.content)

# Async variant
async_client = ClientFactory.create_async_client("PollinationsAI")
```
```

--------------------------------

### Image Generation with GPT4Free Python Client

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Shows how to generate an image using the GPT4Free Python client. Requires the 'g4f' library.

```python
import g4f

response = g4f.Image.create(
    prompt="A cute cat",
    model=g4f.models.default,
    provider=g4f.Provider.Bing
)
print(response)
```

--------------------------------

### ClientFactory for Pre-configured Clients

Source: https://context7.com/xtekky/gpt4free/llms.txt

Create pre-configured Client or AsyncClient instances using ClientFactory. Supports named providers or custom OpenAI-compatible endpoints.

```python
from g4f.client import ClientFactory

# Named provider
client = ClientFactory.create_client("PollinationsAI")
response = client.chat.completions.create(
    model="openai-large",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Custom OpenAI-compatible endpoint (e.g. a local LM Studio server)
client = ClientFactory.create_client(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio"
)
response = client.chat.completions.create(
    model="lmstudio-community/Meta-Llama-3-8B-Instruct-GGUF",
    messages=[{"role": "user", "content": "What is 2+2?"}]
)
print(response.choices[0].message.content)

# Async variant
async_client = ClientFactory.create_async_client("PollinationsAI")
```

--------------------------------

### Create Persistent Directories for Docker

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Use these commands to create and set ownership for directories that will store HAR/cookies and generated media when running GPT4Free in Docker. This is crucial for persistent data storage.

```bash
mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media
sudo chown -R 1200:1201 ${PWD}/har_and_cookies ${PWD}/generated_media
```

--------------------------------

### Asynchronous Text Generation with GPT4Free Python Client

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Illustrates using the asynchronous client for text generation. Requires the 'g4f' library and an async event loop.

```python
import g4f
import asyncio

async def main():
    response = await g4f.ChatCompletion.create_async(
        model=g4f.models.default,
        messages=[{"role": "user", "content": "Hello world"}],
        provider=g4f.Provider.Bing
    )
    print(response)

asyncio.run(main())
```

--------------------------------

### Interference REST API — `POST /v1/chat/completions`

Source: https://context7.com/xtekky/gpt4free/llms.txt

The FastAPI server exposes OpenAI-compatible endpoints for chat completions. Start the server with `python -m g4f --port 1337`.

```APIDOC
## Interference REST API — `POST /v1/chat/completions`

The FastAPI server exposes OpenAI-compatible endpoints. Start it with `python -m g4f --port 1337`.

```bash
# Non-streaming
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is 2+2?"}]
  }'

# Streaming with explicit provider
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "",
    "provider": "PollinationsAI",
    "stream": true,
    "messages": [{"role": "user", "content": "Count to 3."}]
  }'

# With conversation_id for stateful sessions (server keeps state)
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "",
    "provider": "Copilot",
    "stream": true,
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "messages": [{"role": "user", "content": "My name is Bob."}]
  }'
```

Python client using `requests` with SSE streaming:

```python
import requests, json, uuid

url = "http://localhost:1337/v1/chat/completions"
body = {
    "model": "", "provider": "Copilot", "stream": True,
    "conversation_id": str(uuid.uuid4()),
    "messages": [{"role": "user", "content": "Hello, I am Heiner."}]
}
resp = requests.post(url, json=body, stream=True)
resp.raise_for_status()
for line in resp.iter_lines():
    if line.startswith(b"data: "):
        data = json.loads(line[6:])
        content = data.get("choices", [{}])[0].get("delta", {}).get("content", "")
        if content:
            print(content, end="")
```
```

--------------------------------

### Interference REST API: POST /v1/chat/completions (Non-streaming)

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use this endpoint to send chat completion requests to the FastAPI server. Ensure the server is started with `python -m g4f --port 1337`.

```bash
# Non-streaming
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is 2+2?"}]
  }'
```

--------------------------------

### Smooth Scrolling for Anchor Links

Source: https://github.com/xtekky/gpt4free/blob/main/etc/tool/template.html

Implements smooth scrolling when anchor links (href starting with '#') are clicked. This enhances user experience by preventing jarring page jumps. It requires the target element to exist on the page.

```javascript
document.addEventListener('click', function(e) {
    if (e.target.tagName === 'A' && e.target.getAttribute('href').startsWith('#')) {
        e.preventDefault();
        const target = document.querySelector(e.target.getAttribute('href'));
        if (target) {
            target.scrollIntoView({ behavior: 'smooth', block: 'start' });
        }
    }
});
```

--------------------------------

### Configure Windows ARM64 Build Matrix

Source: https://github.com/xtekky/gpt4free/blob/main/docs/arm64-build-plan.md

Define the build matrix for Windows executables, including a placeholder for ARM64 architecture that will utilize `windows-latest-arm64` runners when they become available.

```yaml
build-windows-exe:
  strategy:
    matrix:
      include:
        - architecture: x64
          runner: windows-latest
          runner-arch: x86_64
        - architecture: arm64  
          runner: windows-latest-arm64  # When available
          runner-arch: arm64
```

--------------------------------

### Test gpt4free Client

Source: https://github.com/xtekky/gpt4free/blob/main/SKILL.md

Test the gpt4free client with a specific model, such as 'openclaw'.

```bash
g4f client "Hello" --model openclaw
```

--------------------------------

### Triggering a Build with Git Tags

Source: https://github.com/xtekky/gpt4free/blob/main/docs/build-workflow.md

Push a version tag to the repository to automatically trigger the build workflow. This process detects the tag, builds all package formats in parallel, creates a GitHub release, and publishes to PyPI.

```bash
git tag v1.2.3
git push origin v1.2.3
```

--------------------------------

### Audio Generation and Transcription with AsyncClient

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use AsyncClient for text-to-speech and audio transcription. Ensure you have a 'recording.wav' file for transcription.

```python
import asyncio
from g4f.client import AsyncClient
import g4f.Provider

async def main():
    client = AsyncClient(provider=g4f.Provider.PollinationsAI)

    # Text-to-speech: generates an MP3 file
    tts = await client.chat.completions.create(
        model="openai-audio",
        messages=[{"role": "user", "content": "Say good day to the world"}],
        audio={"voice": "alloy", "format": "mp3"},
    )
    tts.choices[0].message.save("alloy.mp3")

    # Audio transcription
    with open("recording.wav", "rb") as audio_file:
        transcript = await client.chat.completions.create(
            messages="Transcribe this audio",
            provider=g4f.Provider.Microsoft_Phi_4,
            media=[[audio_file, "recording.wav"]],
            modalities=["text"],
        )
        print(transcript.choices[0].message.content)

asyncio.run(main())
```

--------------------------------

### Client — Synchronous OpenAI-compatible client

Source: https://context7.com/xtekky/gpt4free/llms.txt

The primary high-level synchronous entry point for interacting with g4f. Its interface closely mirrors the `openai.OpenAI` client, allowing for easy integration with existing applications. It supports optional parameters like `provider`, `api_key`, `base_url`, and `proxies`.

```APIDOC
## Client — Synchronous OpenAI-compatible client

The main high-level synchronous entry point. Its interface mirrors `openai.OpenAI`. Accepts an optional `provider`, `api_key`, `base_url`, and `proxies`.

```python
from g4f.client import Client

client = Client()  # auto-select provider

# Basic chat completion
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user",   "content": "How does a court case reach the Supreme Court?"}
    ]
)
print(response.choices[0].message.content)
# response.choices[0].message.role  → "assistant"
# response.usage.completion_tokens  → int

# Streaming
for chunk in client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello." }],
    stream=True
):
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

# With stop tokens and max_tokens
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Repeat 'hello' 100 times." }],
    max_tokens=20,
    stop=["hello hello hello"]
)
print(response.choices[0].finish_reason)  # "stop" or "length"
```
```

--------------------------------

### Vision/Multimodal Inputs with gpt4free

Source: https://context7.com/xtekky/gpt4free/llms.txt

Enable vision capabilities by passing image data via the `image` parameter in `client.chat.completions.create`. Supports remote image URLs (fetched as bytes) and local image files.

```python
import requests
from g4f.client import Client
import g4f.models

client = Client()

# Analyse a remote image
image_bytes = requests.get(
    "https://raw.githubusercontent.com/xtekky/gpt4free/refs/heads/main/docs/images/cat.jpeg",
    stream=True
).content

response = client.chat.completions.create(
    model=g4f.models.default_vision,
    messages=[{"role": "user", "content": "Describe what is in this image."}],
    image=image_bytes
)
print(response.choices[0].message.content)

# Analyse a local image file
with open("photo.jpg", "rb") as local_img:
    response = client.chat.completions.create(
        model=g4f.models.default_vision,
        messages=[{"role": "user", "content": "What objects are visible?"}],
        image=local_img
    )
    print(response.choices[0].message.content)
```

--------------------------------

### Async Image Generation with gpt4free

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use `AsyncClient.images.generate` for asynchronous image generation. This is the async counterpart to synchronous image generation and requires `asyncio` to run.

```python
import asyncio
from g4f.client import AsyncClient

async def main():
    client = AsyncClient()
    response = await client.images.generate(
        model="flux",
        prompt="photorealistic mountain landscape at dawn",
        response_format="url"
    )
    for image in response.data:
        print(f"URL: {image.url}  |  Prompt: {image.revised_prompt}")

asyncio.run(main())
```

--------------------------------

### RetryProvider / IterListProvider - Multi-provider fallback chains

Source: https://context7.com/xtekky/gpt4free/llms.txt

Explains how to use `RetryProvider` and `IterListProvider` to create fallback chains for multiple providers, allowing automatic fallback on failure or exhaustion.

```APIDOC
## `RetryProvider` / `IterListProvider` — Multi-provider fallback chains

Wrap multiple providers so that g4f automatically falls back to the next one on failure or exhaustion.

```python
from g4f.client import Client
from g4f.Provider import OpenaiChat, PollinationsAI, RetryProvider

# Retry a single provider up to 5 times before giving up
client = Client(
    provider=RetryProvider(
        [OpenaiChat],
        single_provider_retry=True,
        max_retries=5
    ),
    proxies={
        "http":  "http://user:pass@proxy-host:port",
        "https": "http://user:pass@proxy-host:port"
    }
)

# Fall through an ordered list of providers
from g4f.Provider import IterListProvider, Groq, DeepInfra, PollinationsAI

fallback_client = Client(
    provider=IterListProvider([Groq, DeepInfra, PollinationsAI], shuffle=False)
)
response = fallback_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Give me a haiku about code."}]
)
print(response.choices[0].message.content)
```
```

--------------------------------

### Python Async Client Usage

Source: https://github.com/xtekky/gpt4free/blob/main/README.md

Illustrates the usage of asynchronous variants of the GPT4Free client via `AsyncClient`. This is suitable for non-blocking operations.

```python
AsyncClient
```

--------------------------------

### Synchronous OpenAI-compatible Client with g4f

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use the high-level `Client` for synchronous operations, mirroring the `openai.OpenAI` interface. It supports auto-provider selection and optional configuration.

```python
from g4f.client import Client

client = Client()  # auto-select provider

# Basic chat completion
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user",   "content": "How does a court case reach the Supreme Court?"}
    ]
)
print(response.choices[0].message.content)
# response.choices[0].message.role  → "assistant"
# response.usage.completion_tokens  → int

# Streaming
for chunk in client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello."}
    stream=True
):
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

# With stop tokens and max_tokens
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Repeat 'hello' 100 times."}
    max_tokens=20,
    stop=["hello hello hello"]
)
print(response.choices[0].finish_reason)  # "stop" or "length"
```

--------------------------------

### Client Images Generate

Source: https://context7.com/xtekky/gpt4free/llms.txt

Shows how to use the synchronous Client for image generation, with options for saving locally, returning URLs, or base64 encoded data.

```APIDOC
## `Client.images.generate` — Synchronous image generation

Generates one or more images from a text prompt. Returns an `ImagesResponse` with a `data` list of `Image` objects.

```python
from g4f.client import Client

client = Client()

# Default: saves to local media directory, returns local URL
response = client.images.generate(
    model="flux",
    prompt="a white siamese cat sitting on a windowsill at sunset"
)
print(response.data[0].url)        # /media/<filename>.png
print(response.data[0].revised_prompt)

# Return original remote URL without local download
response_url = client.images.generate(
    model="flux",
    prompt="futuristic cityscape",
    response_format="url"
)
print(response_url.data[0].url)    # https://...

# Return base64-encoded image data
response_b64 = client.images.generate(
    model="flux",
    prompt="abstract geometric art",
    response_format="b64_json"
)
print(response_b64.data[0].b64_json[:40])  # iVBORw0KGgo...
```
```

--------------------------------

### AsyncClient Chat Completions

Source: https://context7.com/xtekky/gpt4free/llms.txt

Demonstrates how to use the AsyncClient for chat completions, including single responses and streaming responses.

```APIDOC
## `AsyncClient` — Asynchronous OpenAI-compatible client

Drop-in async counterpart of `Client`. All methods are awaitable or return async iterators.

```python
import asyncio
from g4f.client import AsyncClient

async def main():
    client = AsyncClient()

    # Single response
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user",   "content": "How does a court case reach the Supreme Court?"}
        ]
    )
    print(response.choices[0].message.content)

    # Async streaming
    stream = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Say hello there!"}],
        stream=True,
    )
    accumulated = ""
    async for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            content = chunk.choices[0].delta.content
            accumulated += content
            print(content, end="", flush=True)
    print("\nFull response:", accumulated)

asyncio.run(main())
```
```

--------------------------------

### List All Working Providers

Source: https://context7.com/xtekky/gpt4free/llms.txt

Retrieve a list of all currently active providers by querying the /v1/providers endpoint.

```bash
curl http://localhost:1337/v1/providers | python -m json.tool
```

--------------------------------

### Programmatic MCP Tool Call (Python)

Source: https://context7.com/xtekky/gpt4free/llms.txt

Interact with MCP tools like web search and image generation programmatically using Python's asyncio and the MCPServer.

```python
import asyncio, json
from g4f.mcp.server import MCPServer, MCPRequest

async def main():
    server = MCPServer()

    # Web search
    req = MCPRequest(jsonrpc="2.0", id=1, method="tools/call",
                     params={"name": "web_search",
                             "arguments": {"query": "Python async tutorial", "max_results": 3}})
    resp = await server.handle_request(req)
    print(json.loads(resp.result["content"][0]["text"]))

    # Image generation
    req = MCPRequest(jsonrpc="2.0", id=2, method="tools/call",
                     params={"name": "image_generation",
                             "arguments": {"prompt": "sunset over the mountains", "model": "flux",
                                           "width": 512, "height": 512}})
    resp = await server.handle_request(req)
    result = json.loads(resp.result["content"][0]["text"])
    print(result.get("url") or result.get("image", "")[:60] + "...")

asyncio.run(main())
```

--------------------------------

### Video Generation with HuggingFaceMedia Provider

Source: https://context7.com/xtekky/gpt4free/llms.txt

Generate video clips using HuggingFace media models. Replace 'hf_your_token_here' with your actual Hugging Face API token.

```python
import g4f.Provider
from g4f.client import Client

client = Client(
    provider=g4f.Provider.HuggingFaceMedia,
    api_key="hf_your_token_here"
)

# List available video models
video_models = client.models.get_video()
print(video_models)

# Generate a video
result = client.media.generate(
    model=video_models[0],
    prompt="A time-lapse of flowers blooming in spring.",
    response_format="url"
)
print(result.data[0].url)
```

--------------------------------

### Image Generation with Different Response Formats

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use the /v1/images/generations endpoint to generate images. Specify 'response_format' as 'url', 'b64_json', or omit for local file saving.

```bash
curl http://localhost:1337/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model": "flux", "prompt": "a neon cyberpunk city at night"}'
```

```bash
curl http://localhost:1337/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model": "flux", "prompt": "a peaceful forest lake", "response_format": "url"}'
```

```bash
curl http://localhost:1337/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model": "flux", "prompt": "abstract art", "response_format": "b64_json"}'
```

--------------------------------

### Python Input Format Support

Source: https://github.com/xtekky/gpt4free/blob/main/docs/reasoning-standardization.md

This Python code snippet demonstrates how the system continues to accept both 'reasoning_content' and 'reasoning' fields for input, ensuring backward compatibility.

```python
reasoning_content = choice.get("delta", {}).get("reasoning_content", choice.get("delta", {}).get("reasoning"))
```

--------------------------------

### create_custom_provider - Dynamic custom provider class

Source: https://context7.com/xtekky/gpt4free/llms.txt

Details how to use `create_custom_provider` to dynamically create a new provider class at runtime that wraps any OpenAI-compatible endpoint.

```APIDOC
## `create_custom_provider` — Dynamic custom provider class

Creates a new provider class at runtime that wraps any OpenAI-compatible endpoint.

```python
from g4f.client import create_custom_provider, Client

MyProvider = create_custom_provider(
    base_url="https://api.together.xyz/v1",
    api_key="your-together-key",
    name="TogetherAI",
    default_model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
    models=["meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
            "mistralai/Mixtral-8x7B-Instruct-v0.1"]
)

client = Client(provider=MyProvider)
response = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
    messages=[{"role": "user", "content": "Hello from Together!"}]
)
print(response.choices[0].message.content)
```
```

--------------------------------

### Multi-provider Fallback Chains with RetryProvider and IterListProvider

Source: https://context7.com/xtekky/gpt4free/llms.txt

Configure fallback chains for providers. RetryProvider retries a single provider, while IterListProvider creates an ordered or shuffled list of providers to try sequentially.

```python
from g4f.client import Client
from g4f.Provider import OpenaiChat, PollinationsAI, RetryProvider

# Retry a single provider up to 5 times before giving up
client = Client(
    provider=RetryProvider(
        [OpenaiChat],
        single_provider_retry=True,
        max_retries=5
    ),
    proxies={
        "http":  "http://user:pass@proxy-host:port",
        "https": "http://user:pass@proxy-host:port"
    }
)

# Fall through an ordered list of providers
from g4f.Provider import IterListProvider, Groq, DeepInfra, PollinationsAI

fallback_client = Client(
    provider=IterListProvider([Groq, DeepInfra, PollinationsAI], shuffle=False)
)
response = fallback_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Give me a haiku about code."}]
)
print(response.choices[0].message.content)
```

--------------------------------

### Configure Linux ARM64 Build Matrix

Source: https://github.com/xtekky/gpt4free/blob/main/docs/arm64-build-plan.md

Add ARM64 architecture to the build matrix in `.github/workflows/build-packages.yml` to enable native Linux ARM64 builds using dedicated runners.

```yaml
# Add to .github/workflows/build-packages.yml
build-linux-exe:
  strategy:
    matrix:
      include:
        - architecture: x64
          runner: ubuntu-latest
          runner-arch: x86_64
        - architecture: arm64
          runner: buildjet-4vcpu-ubuntu-2204-arm  # ARM64 runners
          runner-arch: aarch64
```

--------------------------------

### Run MCP Server in HTTP Mode

Source: https://context7.com/xtekky/gpt4free/llms.txt

Launch the MCP server in HTTP mode, exposing JSON-RPC endpoints for AI assistant communication. Specify the port for the server.

```bash
python -m g4f.mcp --http --port 8765
```

--------------------------------

### Low-level Synchronous Chat Completion with g4f

Source: https://context7.com/xtekky/gpt4free/llms.txt

Use `g4f.ChatCompletion.create` for synchronous chat. It automatically selects a provider and can return a plain string or stream token chunks.

```python
import g4f

# Non-streaming – returns a plain string
response = g4f.ChatCompletion.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user",   "content": "What is the capital of France?"}
    ]
)
print(response)  # "Paris."

# Streaming – yields string chunks
for chunk in g4f.ChatCompletion.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Count to 5."}],
    stream=True
):
    print(chunk, end="", flush=True)
```

--------------------------------

### YAML model-routing config (`config.yaml`)

Source: https://context7.com/xtekky/gpt4free/llms.txt

Configure named model routes with provider fallback and quota conditions by placing a `config.yaml` file in the cookies directory.

```APIDOC
## YAML model-routing config (`config.yaml`)

Place a `config.yaml` in the cookies directory (`~/.g4f/` or `./har_and_cookies/`) to declaratively define named model routes with provider fallback and quota conditions.

```yaml
# ~/.g4f/config.yaml
models:
  # Primary: OpenAI account if quota available, else Pollinations
  - name: "my-gpt4"
    providers:
      - provider: "OpenaiAccount"
        model: "gpt-4o"
        condition: "balance > 0 or error_count < 3"
      - provider: "PollinationsAI"
        model: "openai-large"

  # Groq with Llama, fallback to DeepInfra
  - name: "llama-fast"
    providers:
      - provider: "Groq"
        model: "llama-3.3-70b"
        condition: "error_count < 3"
      - provider: "DeepInfra"
        model: "meta-llama/Llama-3.3-70B-Instruct"
```

Use the named route in any client:

```python
from g4f.client import Client
client = Client()
response = client.chat.completions.create(
    model="my-gpt4",  # defined in config.yaml
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```
```

--------------------------------

### create_custom_provider for Dynamic Providers

Source: https://context7.com/xtekky/gpt4free/llms.txt

Dynamically create a new provider class that wraps any OpenAI-compatible endpoint. Requires specifying API details and available models.

```python
from g4f.client import create_custom_provider, Client

MyProvider = create_custom_provider(
    base_url="https://api.together.xyz/v1",
    api_key="your-together-key",
    name="TogetherAI",
    default_model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
    models=["meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
            "mistralai/Mixtral-8x7B-Instruct-v0.1"]
)

client = Client(provider=MyProvider)
response = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
    messages=[{"role": "user", "content": "Hello from Together!"}]
)
print(response.choices[0].message.content)
```
Tokens:
Raw