G4F (GPT4Free)

Common errors

• g4f.errors.RateLimitError: Response 402: Rate limit

  cause The chosen provider has hit its usage limits for your IP address or session.
  fix Wait for the rate limit to reset, try a different `g4f.Provider`, or use `g4f.Provider.RetryProvider` to automatically cycle through available providers.

• g4f.errors.RetryProviderError: No providers available (All providers failed).

  cause All selected or default providers failed to respond or encountered an error, often due to being offline, blocked, or having unexpected changes.
  fix Ensure you have a stable internet connection. Try explicitly specifying a known working provider (e.g., `client = Client(provider=g4f.Provider.Bing)`). Check the `g4f-working` project for currently active providers.

• Model not found for text completion (e.g., trying to use 'gpt-4o' with a provider that only supports 'gpt-3.5-turbo')

  cause The specified model is not supported by the chosen provider, or the provider has a limited set of available models.
  fix Consult the `g4f` documentation or `g4f.Provider` modules to identify which models are supported by each provider. Experiment with common models like 'gpt-3.5-turbo' or 'gpt-4o-mini' which tend to have broader support.

• UserWarning: Curlm already closed! quitting from process_data

  cause This warning often appears in conjunction with network or provider-related errors, indicating an issue with the underlying cURL library's handling of HTTP requests, particularly during asynchronous operations.
  fix While often a symptom rather than a primary cause, addressing the root provider error (e.g., changing providers, ensuring stable connection) usually resolves this. It can sometimes be safely ignored if the main functionality still works.

Warnings

• breaking G4F operates by routing requests through third-party websites, potentially violating their Terms of Service. This practice can lead to legal and ethical issues, making it unsuitable for production environments or handling sensitive/confidential data.
  Fix: Use at your own risk for personal experimentation or educational purposes only. For production, always opt for official APIs with proper authentication and licensing.
• gotcha Provider instability is common; individual providers may go offline, change their behavior, or introduce rate limits without warning. This can lead to frequent errors or unexpected downtime.
  Fix: Implement robust error handling (e.g., try-except for `g4f.errors.RetryProviderError`, `g4f.errors.RateLimitError`), use `g4f.Provider.RetryProvider` with a list of backup providers, or regularly check community resources like 'g4f-working' for status updates.
• gotcha Some providers require active user sessions and cookies (e.g., from a logged-in browser). While `g4f` attempts to retrieve these automatically in local environments, manual provision might be necessary in non-local deployments.
  Fix: Ensure the environment where `g4f` is run has an active browser session with the required cookies, or configure the client to manually pass cookies if applicable for the chosen provider.
• deprecated Older versions of the library or specific provider implementations might trigger version deprecation warnings or cease to function as underlying third-party APIs change.
  Fix: Always keep the `g4f` library updated using `pip install -U g4f`. If warnings persist, `import warnings; warnings.filterwarnings("ignore")` can suppress them, but updating is generally preferred.

Install

• pip install -U g4f Basic Installation
• pip install -U g4f[all] Full Installation (includes GUI, API, image, webdriver dependencies)

Imports

• Client
  wrong:

  import g4f; response = g4f.ChatCompletion.create(...)

  correct:

  from g4f.client import Client

  The Client API (g4f.client.Client) is the recommended and modern approach for OpenAI-compatible interactions, offering better control and feature access. Direct use of g4f.ChatCompletion.create is still supported but less flexible.
• Provider

  from g4f.Provider import <ProviderName>

  Individual providers are imported from g4f.Provider for explicit selection, e.g., g4f.Provider.Bing, g4f.Provider.OpenaiChat.

Quickstart

This quickstart demonstrates how to use the `g4f.client.Client` to interact with a language model, sending a simple chat message and printing the response. It includes basic error handling for common `g4f` exceptions. Users can explicitly select providers or rely on the library's default/auto-selection.

import g4f
from g4f.client import Client

# Initialize the client. For some providers, additional setup (like a browser executable path) might be needed.
# client = Client(provider=g4f.Provider.Bing, browser_executable_path="/path/to/chrome")
client = Client()

# Define the conversation messages
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello, how are you today?"}
]

try:
    # Create a chat completion
    response = client.chat.completions.create(
        model="gpt-3.5-turbo", # You can specify other models like 'gpt-4o-mini' if available
        messages=messages,
        web_search=False # Set to True to enable web search if supported by the provider
    )

    # Print the response
    if response.choices:
        print(response.choices[0].message.content)
    else:
        print("No response received from the model.")

except g4f.errors.RateLimitError:
    print("Rate limit exceeded. Please try again later or switch providers.")
except g4f.errors.RetryProviderError as e:
    print(f"Provider error: {e}. Consider trying a different provider or model.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")