# What Is the Interference API in gpt4free? Complete Technical Guide

> Explore the Interference API in gpt4free, an OpenAI-compatible REST server. Learn how this FastAPI tool enables seamless replacement of official OpenAI services with a multi-provider backend.

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

---

**The Interference API in gpt4free is an OpenAI-compatible REST server built on FastAPI that exposes the library's multi-provider backend through standard HTTP endpoints like `/v1/chat/completions`, enabling drop-in replacement for official OpenAI services.**

The xtekky/gpt4free repository aggregates access to multiple AI providers through a unified asynchronous client. The **Interference API** serves as the HTTP façade that transforms this internal `AsyncClient` into a production-ready web service, allowing any application using standard OpenAI client libraries to route requests through gpt4free's provider-agnostic pipeline without modifying existing code.

## Core Architecture and Implementation Files

The Interference API implementation resides primarily in **[`g4f/api/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/__init__.py)**, which constructs the FastAPI application, registers route handlers, and performs request validation. This module creates a lightweight HTTP server that forwards every validated request to the internal **`AsyncClient`** (defined in [`g4f/client_async.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client_async.py)) for provider resolution and response generation.

The bootstrap entry point is located in **[`g4f/api/run.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/run.py)**, a minimal wrapper that invokes `g4f.api.run_api()` to initialize the server. Provider implementations available for routing are located in **`g4f/Provider/`**, and the selection logic automatically applies based on incoming request parameters or global configuration.

## OpenAI-Compatible Endpoint Specifications

The API mirrors OpenAI's REST contract exactly, implementing the same path structures and JSON schemas. The **`Api.chat_completions`** method (defined around lines 45-48 in [`g4f/api/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/__init__.py)) handles POST requests to **`/v1/chat/completions`**, while **`Api.models`** (lines 126-152) serves GET requests to **`/v1/models`** returning consolidated provider model lists.

**Provider-agnostic routing** occurs automatically for every call. The system selects a concrete provider (e.g., Perplexity, Gemini, or local models) based on either the request's `provider` field or the global **`AppConfig.provider`** setting. This routing logic lives in `g4f/Provider/` and requires no code changes when new providers are added.

## Authentication and Configuration Modes

The Interference API supports two distinct authentication patterns controlled via **`AppConfig`**. 

**Demo mode**: When `AppConfig.demo` is set to `true`, the server runs without requiring an API key, returning a demo-user context for all incoming requests. This is useful for local development and testing.

**Key-based authentication**: For production deployments, set **`g4f.config.g4f_api_key`**. When configured, the API requires the **`g4f-api-key`** header on all requests, rejecting unauthorized calls with standard HTTP 401 responses.

## Streaming Responses and Media Support

The API supports both synchronous JSON responses and **Server-Sent Events (SSE)** streaming. When `stream: true` is passed in the request body, the **`Api.chat_completions`** method (around lines 223-237) returns a **`StreamingResponse`** object that yields content chunks as SSE `data:` events.

Beyond text generation, the API handles multimedia through dedicated routes. The **`Api.generate_image`** method (lines 557-587) processes **`/v1/media/generate`** and **`/v1/images/generations`** endpoints, forwarding requests to image-specific providers and returning generated URLs. Additional routes support audio transcription, speech synthesis, and arbitrary file upload/download operations.

## Starting the Interference API Server

You can start the server via command line or programmatically.

**CLI startup** (most common):

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

```

The `--debug` flag enables request logging through the FastAPI stack.

**Programmatic startup**:

```python
import g4f.api
g4f.api.run_api(debug=True)

```

This pattern is used internally by [`g4f/api/run.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/run.py) when executing the module entry point.

## Integration Examples

### Standard Chat Completions with the OpenAI SDK

Point the official OpenAI client at your local Interference API:

```python
import openai

openai.api_base = "http://localhost:8080/v1"
openai.api_key = "any-value-if-key-required"

resp = openai.ChatCompletion.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain the Interference API"}],
    stream=False
)

print(resp["choices"][0]["message"]["content"])

```

This request hits the `/v1/chat/completions` route in [`g4f/api/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/__init__.py) and processes through `Api.chat_completions`.

### Streaming Responses via Server-Sent Events

```python
import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": "Stream this response"}],
        "stream": True
    },
    stream=True
)

for line in resp.iter_lines():
    if line:
        print(line.decode())

```

The endpoint returns a `StreamingResponse` where each chunk is yielded as an SSE event.

### Image Generation Endpoints

```python
import openai

openai.api_base = "http://localhost:8080/v1"
openai.api_key = "dummy"

result = openai.Image.create(
    model="flux",
    prompt="a futuristic cityscape at sunset",
    n=1,
    size="1024x1024"
)

print(result["data"][0]["url"])

```

This maps to `/v1/media/generate` and is handled by `Api.generate_image` in the main API module.

### Raw HTTP Requests

List available models via direct HTTP:

```bash
curl -X POST http://localhost:8080/v1/models

```

This calls `Api.models()` and returns the aggregated model list from all configured providers.

## Summary

- The **Interference API** is implemented in [`g4f/api/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/__init__.py) as a FastAPI application that wraps the internal `AsyncClient`.
- It provides **OpenAI-compatible endpoints** including `/v1/chat/completions`, `/v1/models`, and media routes, enabling drop-in SDK replacement.
- **Provider routing** is automatic based on the `provider` request field or global `AppConfig.provider` settings.
- **Authentication** is optional in demo mode (`AppConfig.demo = true`) or enforced via the `g4f-api-key` header when `g4f.config.g4f_api_key` is configured.
- **Streaming** is supported through Server-Sent Events (`StreamingResponse`), and **media generation** (images, audio) is available via dedicated endpoints.

## Frequently Asked Questions

### What is the Interference API in gpt4free used for?

The Interference API provides a standards-compliant HTTP interface that exposes gpt4free's multi-provider backend. It allows developers to use existing OpenAI client libraries and tools while routing traffic through gpt4free's free provider ecosystem, effectively creating a drop-in alternative to OpenAI's commercial API.

### How do I start the Interference API server locally?

Execute `python -m g4f --port 8080 --debug` from your terminal. This command invokes `g4f.api.run_api()` via the bootstrap file [`g4f/api/run.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/run.py), starting the FastAPI server on the specified port with optional debug logging enabled.

### Does the Interference API support real-time streaming responses?

Yes. When you set `stream: true` in your request payload to `/v1/chat/completions`, the API returns a `StreamingResponse` (implemented around lines 223-237 in [`g4f/api/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/__init__.py)) that yields content via Server-Sent Events (SSE), compatible with OpenAI's streaming protocol.

### Which source files contain the core API implementation?

The main FastAPI application logic, route definitions, and request handling reside in **[`g4f/api/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/__init__.py)**. The bootstrap entry point is **[`g4f/api/run.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/api/run.py)**. Underlying client functionality used by the API is located in **[`g4f/client_async.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client_async.py)** and **[`g4f/client.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client.py)**, while available providers are defined in the **`g4f/Provider/`** directory.