GPT4Free

https://g4f.dev/docs/
Admin
GPT4Free provides free and convenient AI endpoints for text generation, image generation, and other...
Tokens:45,500
Snippets:665
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### API Key Setup - Python Example

Source: https://g4f.dev/docs/config.html

Example of using an API key in Python with g4f client.

```python
import os
from g4f.client import Client
from g4f.Provider import OpenaiAPI
client = Client(provider=OpenaiAPI, api_key=os.getenv("OPENAI_API_KEY"))
```

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

### Using a Vision Model Example

Source: https://g4f.dev/docs/client.html

An incomplete example demonstrating the setup for using a vision model.

```python
import g4f
import requests

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

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

### Verify Installation (Basic)

Source: https://g4f.dev/docs/git.html

Basic Python code snippet to start using G4F functionalities after installation.

```python
import g4f
# Your code here
```

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

### Install Dependencies (Minimum Requirements)

Source: https://g4f.dev/docs/git.html

Command to install minimum dependencies from requirements-slim.txt.

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

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

### Install Dependencies (All Packages)

Source: https://g4f.dev/docs/git.html

Command to install all dependencies from requirements.txt for a full installation.

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

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

### Usage Example

Source: https://g4f.dev/docs/git.html

Example of how to use the G4F client to make a chat completion request.

```python
import g4f

# Your G4F code here
# For example:
from g4f.client import Client

client = Client()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "Say this is a test"
        }
    ]
    # Add any other necessary parameters
)

print(response.choices[0].message.content)
```

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

### HAR File Setup - Example Auto-Loading HAR in Python

Source: https://g4f.dev/docs/config.html

Example of auto-loading .har and .json cookie files from the cookies directory.

```python
from g4f.cookies import read_cookie_files
read_cookie_files()  # Auto-loads all .har and .json cookie files in the cookies dir
```

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

### Run the Server (Non-Docker Method)

Source: https://g4f.dev/docs/docker.html

Starts the gpt4free server using the Python module.

```bash
python -m g4f.api.run
```

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

### Installation

Source: https://g4f.dev/docs/client_cli.html

Install the g4f library with all extras.

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

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

### Command-line Chat Program Example

Source: https://g4f.dev/docs/client.html

A basic example of a command-line chat program using the G4F Client.

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

# Initialize the GPT client with the desired provider
client = Client()

```

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

### Activate the Virtual Environment (Windows)

Source: https://g4f.dev/docs/git.html

Command to activate the virtual environment on Windows.

```bash
.\venv\Scripts\activate
```

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

### Search Tool Support Example

Source: https://g4f.dev/docs/client.html

Demonstrates how to use the search tool for retrieving real-time data during chat completions.

```python
from g4f.client import Client

client = Client()

tool_calls = [
    {
        "function": {
            "arguments": {
                "query": "Latest advancements in AI",
                "max_results": 5,
                "max_words": 2500,
                "backend": "auto",
                "add_text": True,
                "timeout": 5
            },
            "name": "search_tool"
        },
        "type": "function"
    }
]

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Tell me about recent advancements in AI."}
    ],
    tool_calls=tool_calls
)

print(response.choices[0].message.content)
```

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

### Set Up a Python Virtual Environment

Source: https://g4f.dev/docs/git.html

Command to create a Python virtual environment named 'venv'.

```bash
python3 -m venv venv
```

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

### Text Completions Example

Source: https://g4f.dev/docs/client.html

Demonstrates how to generate text completions using the ChatCompletions endpoint.

```python
from g4f.client import Client

client = Client()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "Say this is a test"
        }
    ]
)

print(response.choices[0].message.content)
```

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

### Generate a video using a prompt

Source: https://g4f.dev/docs/async_client.html

This example demonstrates how to generate a video from a text prompt using the `HuggingFaceMedia` provider and retrieve its URL.

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

async def main():
    client = AsyncClient(
        provider=HuggingFaceMedia,
        api_key="hf_***"  # Your API key here
    )

    # Get available video models
    video_models = client.models.get_video()
    print("Available Video Models:", video_models)

    # Generate video
    result = await client.media.generate(
        model=video_models[0],
        prompt="G4F AI technology is the best in the world.",
        response_format="url"
    )

    print("Generated Video URL:", result.data[0].url)

asyncio.run(main())
```

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

### Initializing the Client with Custom Providers

Source: https://g4f.dev/docs/client.html

Example of initializing the G4F Client with specific providers for chat and image generation.

```python
from g4f.client import Client
from g4f.Provider import BingCreateImages, OpenaiChat, Gemini

client = Client(
    provider=OpenaiChat,
    image_provider=Gemini,
    # Add any other necessary parameters
)
```

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

### Provider Initialization Examples

Source: https://g4f.dev/docs/client_js.html

Examples of initializing the client with different supported providers like PollinationsAI, DeepInfra, HuggingFace, Together.AI, Puter, and a custom client.

```javascript
import { Client, PollinationsAI, DeepInfra, Together, Puter, HuggingFace } from '@gpt4free/g4f.dev';

// Pollinations
const client = new PollinationsAI({ apiKey: 'optional' });

// DeepInfra
const client = new DeepInfra({ apiKey: 'optional' });

// HuggingFace
const client = new HuggingFace({ apiKey: 'required' });

// Together.AI
const client = new Together({ apiKey: 'required' });

// Puter
const client = new Puter();

// Custom (e.g., local GPT4Free instance)
const client = new Client({baseUrl: 'http://localhost:8080/v1', apiKey: 'secret'});
```

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

### Environment Variable & API Key Configuration

Source: https://g4f.dev/docs/config.html

Example .env file for API keys.

```dotenv
HUGGINGFACE_API_KEY=
POLLINATIONS_API_KEY=
GEMINI_API_KEY=
TOGETHER_API_KEY=
DEEPINFRA_API_KEY=
OPENAI_API_KEY=
GROQ_API_KEY=
OPENROUTER_API_KEY=
```

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

### Streaming Completions Example

Source: https://g4f.dev/docs/client.html

Shows how to process responses incrementally as they are generated using the stream=True option.

```python
from g4f.client import Client

client = Client()

stream = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {
            "role": "user",
            "content": "Say this is a test"
        }
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content or "", end="")
```

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

### Full Stack Installation

Source: https://g4f.dev/docs/gui.html

Installs all necessary dependencies, including browser support for web-based interactions.

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

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

### Conversation Memory Usage Example

Source: https://g4f.dev/docs/client.html

A simple example demonstrating how to use the Conversation class to get a response from the AI.

```python
conversation = Conversation()
response = conversation.get_response("Hello, how are you?")
print(response)
```

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

### Python Example

Source: https://g4f.dev/docs/providers/perplexity.md

A basic example of how to use the Perplexity provider in Python to get a response.

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

# No API key required
client = Client(provider=Perplexity)

response = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "What are the latest developments in AI?"}
    ],
)

print(response.choices[0].message.content)
```

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

### Debug Mode - Example Debug Log

Source: https://g4f.dev/docs/config.html

An example of what debug log output might look like.

```text
Read .har file: ./har_and_cookies/you.com.har
Cookies added: 10 from .you.com
Read cookie file: ./har_and_cookies/google.json
Cookies added: 16 from .google.com
```

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

### Clone the Repository

Source: https://g4f.dev/docs/git.html

Command to clone the G4F repository from GitHub.

```bash
git clone https://github.com/xtekky/gpt4free.git
```

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

### NPM Installation

Source: https://g4f.dev/docs/client_js.html

How to install the GPT4Free.js client library using NPM.

```bash
npm install @gpt4free/g4f.dev
```

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

### Search Tool Support Example

Source: https://g4f.dev/docs/async_client.html

Illustrates how to use the Search Tool Support feature to trigger a web search during chat completions for real-time data retrieval.

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

async def main():
    client = AsyncClient()

    tool_calls = [
        {
            "function": {
                "arguments": {
                    "query": "Latest advancements in AI",
                    "max_results": 5,
                    "max_words": 2500,
                    "backend": "auto",
                    "add_text": True,
                    "timeout": 5
                },
                "name": "search_tool"
            },
            "type": "function"
        }
    ]

    response = await client.chat.completions.create(
        model="gpt-4",
        messages=[
            {
                "role": "user",
                "content": "Tell me about recent advancements in AI."
            }
        ],
        tool_calls=tool_calls
    )

    print(response.choices[0].message.content)

if __name__ == "__main__":
    asyncio.run(main())
```

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

### Initializing the AsyncClient

Source: https://g4f.dev/docs/async_client.html

To use the G4F AsyncClient, create a new instance. This example shows how to initialize the client with specific providers for chat and image generation.

```python
from g4f.client import AsyncClient
from g4f.Provider import OpenaiChat, Gemini

client = AsyncClient(
    provider=OpenaiChat,
    image_provider=Gemini,
    # Add other parameters as needed
)
```

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

### Provider Import Example

Source: https://g4f.dev/docs/guides/create_provider.html

Example of how to add the new provider import in the __init__.py file.

```python
from .HogeService import HogeService

__all__ = [
  HogeService,
]
```

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

### Configuration with API Key and Proxy

Source: https://g4f.dev/docs/client.html

Example of configuring the G4F Client with an API key and a proxy for outgoing requests.

```python
from g4f.client import Client

client = Client(
    api_key="your_api_key_here",
    proxies="http://user:pass@host",
    # Add any other necessary parameters
)
```

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

### Navigate to the Project Directory

Source: https://g4f.dev/docs/git.html

Command to change the current directory to the cloned G4F project.

```bash
cd gpt4free
```

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

### Python Example

Source: https://g4f.dev/docs/providers/groq.md

Example of how to use the Groq provider with the g4f client in Python.

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

client = Client(
    provider=Groq,
    api_key="your-groq-api-key"
)

response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "user", "content": "Explain the theory of relativity"}
    ],
)

print(response.choices[0].message.content)
```

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

### Chat Completion Examples

Source: https://g4f.dev/docs/providers-and-models.html

Examples of how to perform chat completions using different client interfaces.

```python
from g4f.client import Client

client = Client()
response = client.chat.completions.create(
    model="",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```

```javascript
import { createClient } from 'https://g4f.dev/dist/js/providers.js';

const client = createClient('default');
const result = await client.chat.completions.create({
    model: 'auto',
    messages: [{ role: 'user', content: 'Hello!' }]
});
console.log(result.choices[0].message.content);
```

```curl
curl https://g4f.space/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

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

### API Key Setup - Environment Variables

Source: https://g4f.dev/docs/config.html

Setting API keys as environment variables for different operating systems.

```shell
# macOS / Linux
export OPENAI_API_KEY="your_key"
export GEMINI_API_KEY="your_key"

# Windows CMD
set OPENAI_API_KEY=your_key

# Windows PowerShell
$env:OPENAI_API_KEY = "your_key"
```

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

### Activate the Virtual Environment (macOS and Linux)

Source: https://g4f.dev/docs/git.html

Command to activate the virtual environment on macOS and Linux.

```bash
source venv/bin/activate
```

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

### JavaScript Example

Source: https://g4f.dev/docs/providers/groq.md

Example of how to use the Groq API directly in JavaScript.

```javascript
const response = await fetch('https://api.groq.com/openai/v1/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_GROQ_API_KEY'
    },
    body: JSON.stringify({
        model: 'llama-3.3-70b-versatile',
        messages: [
            { role: 'user', content: 'Hello!' }
        ]
    })
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

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

### Create variations of an existing image

Source: https://g4f.dev/docs/async_client.html

This example shows how to create variations of an existing image using the `create_variation` method.

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

async def main():
    client = AsyncClient(image_provider=OpenaiChat)
    
    response = await client.images.create_variation(
        image=open("docs/images/cat.jpg", "rb"),
        model="dall-e-3",
        # Add any other necessary parameters
    )
    
    image_url = response.data[0].url
    print(f"Generated image URL: {image_url}")

asyncio.run(main())
```

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

### MarkItDown Installation

Source: https://g4f.dev/docs/file.html

Command to install the markitdown package with all optional dependencies.

```bash
pip install markitdown[all]
```

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

### Python Example

Source: https://g4f.dev/docs/providers/gemini.md

Example of how to use the Gemini provider in Python.

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

# API key is required
client = Client(provider=GeminiPro, api_key="YOUR_GOOGLE_API_KEY")

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ],
)

print(response.choices[0].message.content)
```

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

### Creating Chat Completions

Source: https://g4f.dev/docs/async_client.html

An example of creating chat completions with the AsyncClient. This demonstrates a user prompt and configuration for a non-streaming response.

```python
response = await client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "Say this is a test"
        }
    ]
     # Add other parameters as needed
)
```

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

### Streaming Example

Source: https://g4f.dev/docs/providers/perplexity.md

An example demonstrating how to stream responses from the Perplexity provider.

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

client = Client(provider=Perplexity)

stream = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "Explain quantum computing"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

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

### Python Streaming Example

Source: https://g4f.dev/docs/providers/groq.md

Example of how to use the Groq provider for streaming responses in Python.

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

client = Client(
    provider=Groq,
    api_key="your-groq-api-key"
)

stream = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "user", "content": "Write a poem about AI"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

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

### Python Example

Source: https://g4f.dev/docs/providers/nvidia.md

Example of how to use the Nvidia provider in Python.

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

client = Client(
    provider=Nvidia,
    api_key="your-nvidia-api-key"
)

response = client.chat.completions.create(
    model="deepseek-ai/deepseek-v3.2",
    messages=[
        {"role": "user", "content": "Explain neural networks"}
    ],
)

print(response.choices[0].message.content)
```

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

### Using Web Search Example

Source: https://g4f.dev/docs/backend_api_documentation.html

Example using fetch API to create a conversation with web search enabled.

```javascript
fetch('/backend-api/v2/create?model=gpt-3.5-turbo&prompt=Latest news about AI&web_search=true', {
  method: 'GET'
})
.then(response => {
  // Handle streaming response with web search results
})
Copy
```

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

### Python Example

Source: https://g4f.dev/docs/providers/openrouter.md

Example of how to use the OpenRouter provider in Python with a free model.

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

client = Client(provider=OpenRouter)

response = client.chat.completions.create(
    model="openai/gpt-oss-120b:free",
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ],
)

print(response.choices[0].message.content)
```

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

### File Upload Example

Source: https://g4f.dev/docs/backend_api_documentation.html

Example using FormData to upload a file.

```javascript
// Example using FormData
const formData = new FormData();
formData.append('files', fileObject);

fetch('/backend-api/v2/files/my-bucket', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => console.log(data));
Copy
```

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

### Install g4f with all possible dependencies

Source: https://g4f.dev/docs/requirements.html

Installs the g4f library with all available dependencies.

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

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

### Custom Provider with Instructions Example

Source: https://g4f.dev/docs/client_cli.html

Use a custom provider and set system instructions for the AI.

```bash
g4f client -p PollinationsAI -i "You are a helpful science tutor" "Explain photosynthesis"
```

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

### gpt4free setup script for OpenClaw

Source: https://g4f.dev/docs/guides/openclaw.html

Shell command to download and run the gpt4free setup script for OpenClaw, with a placeholder for the Pollinations API key.

```bash
curl -fsSL https://raw.githubusercontent.com/xtekky/gpt4free/main/scripts/setup-openclaw.sh | bash -s -- <POLLINATIONS_API_KEY>
```

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

### List All Models for All Providers

Source: https://g4f.dev/docs/client_js.html

A comprehensive example demonstrating how to iterate through all built-in providers, create a client for each, fetch their supported models, and log the results.

```javascript
import providers from '@gpt4free/g4f.dev/providers';
import { createClient } from '@gpt4free/g4f.dev/providers';

// Example usage: Fetch and log models for each provider
const providerModels = {};
for (const key of Object.keys(providers)) {
    console.log('Provider:', key, providers[key]);
    try {
        const client = createClient(key);
        providerModels[key] = await client.models.list();
        console.log(`Models for provider "${key}":`, providerModels[key].map(m => m.id));
    } catch (error) {
        console.error(`Error fetching models for provider "${key}":`, error);
    }
}

export { providers, createClient, providerModels };
```

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

### Basic Conversation Example

Source: https://g4f.dev/docs/backend_api_documentation.html

Example using fetch API to create a conversation and handle streaming response.

```javascript
// Example using fetch API
fetch('/backend-api/v2/conversation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-3.5-turbo',
    provider: 'OpenAI',
    messages: [
      {role: 'user', content: 'What is artificial intelligence?'}
    ]
  })
})
.then(response => {
  // Handle streaming response
  const reader = response.body.getReader();
  // Process chunks...
})
Copy
```

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

### Messages Parameter Example

Source: https://g4f.dev/docs/async_client.html

Example of the 'messages' parameter format for the G4F API, showing a system message and a user message.

```python
[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What day is it today?"}
]
```

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

### Use core providers

Source: https://g4f.dev/docs/providers-and-models.html

Initialize a client for a specific core provider like PollinationsAI.

```python
from g4f.client import ClientFactory

client = ClientFactory.create_client("PollinationsAI")
response = client.chat.completions.create(
    model="",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response)
```

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

### Python Example with API Key

Source: https://g4f.dev/docs/providers/openrouter.md

Example of how to use the OpenRouter provider in Python with an API key for premium models.

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

client = Client(
    provider=OpenRouter,
    api_key="your-openrouter-api-key"
)

response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[
        {"role": "user", "content": "Explain machine learning"}
    ],
)

print(response.choices[0].message.content)
```

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

### Python Example

Source: https://g4f.dev/docs/providers/deepinfra.md

Basic usage of the DeepInfra provider in Python to get a chat completion.

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

client = Client(provider=DeepInfra)

response = client.chat.completions.create(
    model="deepseek-r1",
    messages=[
        {"role": "user", "content": "Explain quantum computing"}
    ],
)

print(response.choices[0].message.content)
```

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

### Clear History Example

Source: https://g4f.dev/docs/client_cli.html

Clear the conversation history before starting a new conversation.

```bash
g4f client -C "New conversation"
```

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

### Quick Create

Source: https://g4f.dev/docs/backend_api_documentation.html

Creates a simple conversation with optional web search integration.

```bash
GET /backend-api/v2/create
Copy
```

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

### Checking Response Status

Source: https://g4f.dev/docs/async_client.html

Example of checking if a response contains choices before accessing them.

```python
if response.choices:
    print(response.choices[0].message.content)
else:
    print("No response generated")
```

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

### Example with Video Parameters

Source: https://g4f.dev/docs/media.html

This Python code snippet shows how to generate a video using the HuggingFaceMedia provider, specifying parameters like resolution and aspect ratio.

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

async def main():
    client = AsyncClient(
        provider=HuggingFaceMedia,
        api_key=os.getenv("HF_TOKEN")  # Your API key here
    )

    video_models = client.models.get_video()
    print("Available Video Models:", video_models)

    result = await client.media.generate(
        model=video_models[0],
        prompt="G4F AI technology is the best in the world.",
        resolution="720p",
        aspect_ratio="16:9",
        n=1,
        response_format="url",
    )

    print("Generated Video URL:", result.data[0].url)

asyncio.run(main())
```

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

### Slim Installation

Source: https://g4f.dev/docs/gui.html

This version is lighter, with no browser support, ideal for environments where browser interactions are not required.

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

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

### Build and Run with Docker Compose (Slim)

Source: https://g4f.dev/docs/docker.html

Runs the slim Docker images without Google Chrome support using Docker Compose.

```bash
docker-compose -f docker-compose-slim.yml up -d
```

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

### Multi-turn Conversation

Source: https://g4f.dev/docs/providers/qwencode.md

Example illustrating a multi-turn conversation with the QwenCode provider, starting with a request and then following up with a more specific one.

```python
from g4f.client import Client

client = Client()

messages = [
    {"role": "user", "content": "I need to build a web scraper in Python"}
]

# First response
response = client.chat.completions.create(
    model="qwen3-coder-plus",
    provider="QwenCode",
    messages=messages
)

print("Assistant:", response.choices[0].message.content)

# Follow-up
messages.append({"role": "assistant", "content": response.choices[0].message.content})
messages.append({"role": "user", "content": "Now add error handling and rate limiting"})

response = client.chat.completions.create(
    model="qwen3-coder-plus",
    provider="QwenCode",
    messages=messages
)

print("Assistant:", response.choices[0].message.content)
```

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

### Implementing Rate Limiting with aiolimiter

Source: https://g4f.dev/docs/async_client.html

Example of using 'aiolimiter' to enforce rate limits on API calls.

```python
import asyncio
from aiolimiter import AsyncLimiter

rate_limit = AsyncLimiter(max_rate=10, time_period=1)  # 10 requests per second

async def make_api_call():
    async with rate_limit:
        # Your API call here
        pass
```

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

### Error Handling with try-except

Source: https://g4f.dev/docs/async_client.html

Example of using try-except blocks to catch and handle exceptions during API calls.

```python
try:
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {
                "role": "user",
                "content": "Hello, world!"
            }
        ]
    )
except Exception as e:
    print(f"An error occurred: {e}")
```

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

### Initialize GPT Client and Chat Completion with Image

Source: https://g4f.dev/docs/client.html

Demonstrates how to initialize the GPT client with a specific provider and API key, then create a chat completion that includes an image.

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

client = Client(
    api_key="your_api_key_here",
    provider=GeminiPro
)

image = requests.get("https://raw.githubusercontent.com/xtekky/gpt4free/refs/heads/main/docs/images/cat.jpeg", stream=True).raw
# Or: image = open("docs/images/cat.jpeg", "rb")

response = client.chat.completions.create(
    model=g4f.models.default,
    messages=[
        {
            "role": "user",
            "content": "What's in this image?"
        }
    ],
    image=image
    # Add any other necessary parameters
)

print(response.choices[0].message.content)
```

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

### Text Generation using curl

Source: https://g4f.dev/docs/interference-api.html

Example curl command for text generation via the Interference API.

```bash
curl -X POST "http://localhost:1337/v1/chat/completions" \
     -H "Content-Type: application/json" \
     -d '{
           "messages": [
             {
               "role": "user",
               "content": "Hello"
             }
           ],
           "model": "gpt-4o-mini"
         }'
```

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

### Build and Run with Docker Compose (Full)

Source: https://g4f.dev/docs/docker.html

Pulls the latest Docker image and runs a container with Google Chrome support using Docker Compose.

```bash
docker pull hlohaus789/g4f
docker-compose up -d
```

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

### Creating Chat Completions

Source: https://g4f.dev/docs/client.html

An example of creating chat completions using the G4F Client, specifying the model and messages.

```python
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": "Say this is a test"
        }
    ]
    # Add any other necessary parameters
)
```

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

### Configure custom providers

Source: https://g4f.dev/docs/providers-and-models.html

Initialize clients with custom provider IDs and API keys.

```python
from g4f.client import ClientFactory

client = ClientFactory.create_client("custom:srv_mjlq1ncq8a3f7fe0aea0", api_key="g4f_api_key")
response = client.chat.completions.create(
    model="turbo",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response)
```

```javascript

import { createClient } from 'https://g4f.dev/dist/js/providers.js';

const client = createClient("custom:srv_mjlq1ncq8a3f7fe0aea0");
const result = await client.chat.completions.create({
    model: 'turbo',
    messages: [{ role: 'user', content: 'Explain quantum computing' }]
});
console.log(result);
```

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

### Cookie Configuration - Check Current Cookies Directory Path

Source: https://g4f.dev/docs/config.html

Getting the current directory path where cookies are loaded from.

```python
from g4f.cookies import get_cookies_dir
print(get_cookies_dir())
```

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

### Testing the Provider

Source: https://g4f.dev/docs/guides/create_provider.html

Example code to test the newly created provider.

```python
import g4f

response = g4f.ChatCompletion.create(
    model='gpt-4o',
    provider=g4f.Provider.PROVIDERNAME,
    messages=[{"role": "user", "content": "test"}],
    stream=True
)

for message in response:
    print(message, flush=True, end='')
```

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

### Logging API Usage

Source: https://g4f.dev/docs/async_client.html

Example of using Python's logging module to log API call success or failure, including token usage.

```python
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def make_api_call():
    try:
        response = await client.chat.completions.create(...)
        logger.info(f"API call successful. Tokens used: {response.usage.total_tokens}")
    except Exception as e:
        logger.error(f"API call failed: {e}")
```

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

### Example with Image Parameters

Source: https://g4f.dev/docs/media.html

Generates an image with specified parameters like width, height, number of images, and response format.

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

async def main():
    client = AsyncClient()

    response = await client.images.generate(
        prompt="a white siamese cat",
        model="flux",
        response_format="url",
        width=512,
        height=512,
        n=2,
    )

    for image in response.data:
        print(f"Generated image URL: {image.url}")

asyncio.run(main())
```

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

### Using Requests Library with Interference API

Source: https://g4f.dev/docs/interference-api.html

Example Python code demonstrating how to send requests to the Interference API using the requests library.

```python
import requests

url = "http://localhost:1337/v1/chat/completions"

body = {
    "model": "gpt-4o-mini",
    "stream": False,
    "messages": [
        {"role": "assistant", "content": "What can you do?"}
    ]
}

json_response = requests.post(url, json=body).json().get('choices', [])

for choice in json_response:
    print(choice.get('message', {}).get('content', ''))
```

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

### Initialize and use G4F Python Client

Source: https://g4f.dev/docs/providers-and-models.html

Use the G4F Python ClientFactory to create chat completions.

```python
from g4f.client import ClientFactory

client = ClientFactory.create_client("default")
response = client.chat.completions.create(
    model="model-router",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response)
```

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

### Using OpenAI Library with Interference API

Source: https://g4f.dev/docs/interference-api.html

Example Python code demonstrating how to use the OpenAI library with the Interference API by setting the base_url.

```python
from openai import OpenAI

# Initialize the OpenAI client
client = OpenAI(
    api_key="secret",  # Set an API key (use "secret" if your provider doesn't require one)
    base_url="http://localhost:1337/v1"  # Point to your local or custom API endpoint
)

# Create a chat completion request
response = client.chat.completions.create(
    model="gpt-4o-mini",  # Specify the model to use
    messages=[{"role": "user", "content": "Write a poem about a tree"}],  # Define the input message
    stream=True,  # Enable streaming for real-time responses
)

# Handle the response
if isinstance(response, dict):
    # Non-streaming response
    print(response.choices[0].message.content)
else:
    # Streaming response
    for token in response:
        content = token.choices[0].delta.content
        if content is not None:
            print(content, end="", flush=True)
```

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

### Image Generation (b64_json format) using curl

Source: https://g4f.dev/docs/interference-api.html

Example curl command for image generation in b64_json format via the Interference API.

```bash
curl -X POST "http://localhost:1337/v1/images/generate" \
     -H "Content-Type: application/json" \
     -d '{
           "prompt": "a white siamese cat",
           "model": "flux",
           "response_format": "b64_json"
         }'
```

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

### Generate images using a specified prompt with URL response

Source: https://g4f.dev/docs/async_client.html

This example demonstrates how to generate an image from a text prompt and receive its URL as the response format.

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

async def main():
    client = AsyncClient()
    
    response = await client.images.generate(
        prompt="a white siamese cat",
        model="flux",
        response_format="url"
        # Add any other necessary parameters
    )
    
    image_url = response.data[0].url
    print(f"Generated image URL: {image_url}")

asyncio.run(main())
```

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

### Image Generation (URL format) using curl

Source: https://g4f.dev/docs/interference-api.html

Example curl command for image generation in URL format via the Interference API.

```bash
curl -X POST "http://localhost:1337/v1/images/generate" \
     -H "Content-Type: application/json" \
     -d '{
           "prompt": "a white siamese cat",
           "model": "flux",
           "response_format": "url"
         }'
```

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

### Reuse Conversation in Chat Completions

Source: https://g4f.dev/docs/async_client.html

This example shows how to maintain a conversation context across multiple chat completion requests using the `conversation` attribute.

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

async def main():
    client = AsyncClient(
        provider=OpenaiAccount
    )

    response = await client.chat.completions.create(
        messages="I was born on 01-01-1999.",
    )

    response = await client.chat.completions.create(
        messages="How old i am? I told you before.",
        conversation=response.conversation
    )

    print(response.conversation.__dict__)
    print(response.choices[0].message.content)

asyncio.run(main())
```

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

### Environment Variable Setup

Source: https://g4f.dev/docs/providers/yupp.md

Instructions for setting the Yupp API key using environment variables.

```bash
# Set your Yupp session token
export YUPP_API_KEY="your-session-token-here"

# Or set multiple accounts (comma-separated)
export YUPP_API_KEY="token1,token2,token3"
```

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

### Clone the Repository (Docker Method)

Source: https://g4f.dev/docs/docker.html

Clones the gpt4free repository to the local machine.

```bash
git clone https://github.com/xtekky/gpt4free.git
cd gpt4free
```

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

### Generate images using a specified prompt with Base64 JSON response

Source: https://g4f.dev/docs/async_client.html

This example demonstrates how to generate an image from a text prompt and receive it as a base64-encoded JSON string.

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

async def main():
    client = AsyncClient()
    
    response = await client.images.generate(
        prompt="a white siamese cat",
        model="flux",
        response_format="b64_json"
        # Add any other necessary parameters
    )
    
    base64_text = response.data[0].b64_json
    print(base64_text)

asyncio.run(main())
```

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

### CLI Image Description

Source: https://g4f.dev/docs

Command-line interface example for describing an image.

```bash
g4f client image.jpg "Describe this image"
```

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

### Initialize and Run a Chat Conversation

Source: https://g4f.dev/docs/client.html

This code snippet demonstrates how to initialize an empty conversation history and then engage in a chat with the AI, including handling user input, getting AI responses, and updating the conversation history.

```python
# Initialize an empty conversation history
messages = []

while True:
    # Get user input
    user_input = input("You: ")

    # Check if the user wants to exit the chat
    if user_input.lower() == "exit":
        print("Exiting chat...")
        break  # Exit the loop to end the conversation

    # Update the conversation history with the user's message
    messages.append({"role": "user", "content": user_input})

    try:
        # Get GPT's response
        response = client.chat.completions.create(
            messages=messages,
            model=g4f.models.default,
        )

        # Extract the GPT response and print it
        gpt_response = response.choices[0].message.content
        print(f"Bot: {gpt_response}")

        # Update the conversation history with GPT's response
        messages.append({"role": "assistant", "content": gpt_response})

    except Exception as e:
        print(f"An error occurred: {e}")
```

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

### Examples with Azure and HuggingSpace provider

Source: https://g4f.dev/docs/image_editing.html

Demonstrates creating image variations using Azure and HuggingSpace providers in Python, including model and prompt specifications.

```python
import asyncio
from pathlib import Path
from g4f.client import AsyncClient
from g4f.Provider import HuggingSpace, Azure
from g4f.cookies import read_cookie_files

# Read cookies and environment variables
read_cookie_files()

client = AsyncClient()

async def main_with_hugging_space():
    result = await client.images.create_variation(
        image=Path("g4f.dev/docs/images/strawberry.jpg"),
        provider=HuggingSpace,
        model="flux-kontext-dev",
        prompt="Change color to black and white",
        response_format="url"
    )
    print(result)

async def main_with_azure():
    result = await client.images.create_variation(
        image=Path("g4f.dev/docs/images/strawberry.jpg"),
        provider=Azure,
        model="flux-kontext",
        prompt="Add text 'Hello World' in the center",
        response_format="url"
    )
    print(result)

asyncio.run(main_with_azure())
```

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

### Python Examples for Various Speech Providers

Source: https://g4f.dev/docs/media.html

Demonstrates how to use the G4F client with different providers (OpenAIFM, PollinationsAI, Gemini, EdgeTTS, gTTS) to generate speech with various configurations.

```python
from g4f.client import Client

from g4f.Provider import gTTS, EdgeTTS, Gemini, PollinationsAI, OpenAIFM

# OpenAIFM
client = Client(provider=OpenAIFM)
response = client.media.generate(
    "Hello",
    model="gpt-4o-mini-tts",
    audio={"voice": "coral"}
)
response.data[0].save("openai_fm.mp3")

# PollinationsAI
client = Client(provider=PollinationsAI)
response = client.media.generate("Hello", audio={"voice": "alloy", "format": "mp3"})
response.data[0].save("openai.mp3")

client = Client(provider=PollinationsAI)
response = client.media.generate("Hello", model="hypnosis-tracy")
response.data[0].save("hypnosis.mp3")

client = Client(provider=Gemini)
response = client.media.generate("Hello", model="gemini-audio")
response.data[0].save("gemini.ogx")

client = Client(provider=EdgeTTS)
response = client.media.generate("Hello", audio={"language": "en"})
response.data[0].save("edge-tts.mp3")

# The EdgeTTS provider also support the audio parameters `rate`, `volume` and `pitch`

client = Client(provider=gTTS)
response = client.media.generate("Hello", audio={"language": "en-US"})
response.data[0].save("google-tts.mp3")

# The gTTS provider also support the audio parameters `tld` and `slow`

```

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

### JavaScript Example

Source: https://g4f.dev/docs/providers/nvidia.md

Example of how to use the Nvidia provider in JavaScript.

```javascript
const response = await fetch('https://integrate.api.nvidia.com/v1/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_NVIDIA_API_KEY'
    },
    body: JSON.stringify({
        model: 'meta/llama-3.3-70b-instruct',
        messages: [
            { role: 'user', content: 'Hello!' }
        ]
    })
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

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

### Python Example

Source: https://g4f.dev/docs/providers/huggingface.md

Demonstrates how to use the HuggingFace provider in Python to list available models and perform a chat completion.

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

# API key is required
client = Client(provider=HuggingFace, api_key="YOUR_HF_TOKEN")

# List available models
models = client.models.get_all()
print(f"Available models: {models[:5]}")

# Chat completion
response = client.chat.completions.create(
    model="meta-llama/Llama-3.1-70B-Instruct",
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ],
)

print(response.choices[0].message.content)
```

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

### JavaScript Example

Source: https://g4f.dev/docs/providers/gemini.md

Example of how to use the Gemini provider in JavaScript.

```javascript
import { createClient } from '@gpt4free/g4f.dev/providers';

const client = await createClient("gemini", { apiKey: 'YOUR_GOOGLE_API_KEY' });

const response = await client.chat.completions.create({
    model: "gemini-2.5-flash",
    messages: [
        { role: "user", content: "Hello, how are you?" }
    ],
});

console.log(response.choices[0].message.content);
```

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

### HTML Installation (CDN)

Source: https://g4f.dev/docs/client_js.html

How to include the GPT4Free.js client library in an HTML file using a CDN.

```html
<script type="module">
  import { Client, PollinationsAI, DeepInfra, Together, Puter, HuggingFace } from 'https://g4f.dev/dist/js/client.js';
</script>
```

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

### JavaScript Example

Source: https://g4f.dev/docs/providers/openrouter.md

Example of how to use the OpenRouter API directly in JavaScript.

```javascript
const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY',
        'HTTP-Referer': 'https://your-site.com'
    },
    body: JSON.stringify({
        model: 'openai/gpt-oss-120b:free',
        messages: [
            { role: 'user', content: 'Hello!' }
        ]
    })
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

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

### Get Version Information

Source: https://g4f.dev/docs/backend_api_documentation.html

Returns current and latest version information.

```bash
GET /backend-api/v2/version
Copy
```

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

### JavaScript Example

Source: https://g4f.dev/docs/providers/anthropic.md

Example of how to use the Anthropic API directly in JavaScript.

```javascript
const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_ANTHROPIC_API_KEY',
        'anthropic-version': '2023-06-01'
    },
    body: JSON.stringify({
        model: 'claude-3-5-sonnet-20241022',
        max_tokens: 1024,
        messages: [
            { role: 'user', content: 'Hello, Claude!' }
        ]
    })
});

const data = await response.json();
console.log(data.content[0].text);
```

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

### Using Specific Models and Providers

Source: https://g4f.dev/docs/async_client.html

Demonstrates how to specify a provider when creating the AsyncClient or in an API call.

```python
client = AsyncClient(provider=g4f.Provider.OpenaiChat)

# or

response = await client.chat.completions.create(
    model="gpt-4",
    provider=g4f.Provider.CopilotAccount,
    messages=[
        {
            "role": "user",
            "content": "Hello, world!"
        }
    ]
)
```
Tokens:
Raw