gpt4free/REST_API_DOCUMENTATION.md

G4F REST API Documentation

Overview

G4F provides a FastAPI-based REST API that is fully compatible with OpenAI's API specifications. This allows you to use existing OpenAI-compatible tools and libraries with G4F's free AI providers.

Getting Started

Starting the API Server

Command Line

# Basic startup
g4f api

# Custom port and debug mode
g4f api --port 8080 --debug

# With GUI interface
g4f api --gui --port 8080

# With authentication
g4f api --g4f-api-key "your-secret-key"

# With custom provider and model defaults
g4f api --provider Copilot --model gpt-4o

# Full configuration example
g4f api \
  --port 8080 \
  --debug \
  --gui \
  --g4f-api-key "secret-key" \
  --provider Copilot \
  --model gpt-4o-mini \
  --proxy "http://proxy.example.com:8080" \
  --timeout 300

Programmatic Startup

from g4f.api import run_api, AppConfig

# Configure the application
AppConfig.set_config(
    g4f_api_key="your-secret-key",
    provider="Copilot",
    model="gpt-4o-mini",
    gui=True,
    timeout=300
)

# Start the server
run_api(host="0.0.0.0", port=8080, debug=True)

Base URL

Once started, the API is available at:

• Default: http://localhost:1337
• Custom port: http://localhost:<PORT>

Authentication

G4F API supports optional authentication via API keys.

Setting Up Authentication

# Start server with authentication
g4f api --g4f-api-key "your-secret-key"

Using Authentication

import openai

client = openai.OpenAI(
    api_key="your-secret-key",
    base_url="http://localhost:1337/v1"
)

HTTP Headers

Authorization: Bearer your-secret-key
# OR
g4f-api-key: your-secret-key

API Endpoints

Chat Completions

POST /v1/chat/completions

Creates a chat completion response.

Request Body:

{
    "model": "gpt-4o-mini",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    "stream": false,
    "max_tokens": 1000,
    "temperature": 0.7,
    "top_p": 0.9,
    "frequency_penalty": 0,
    "presence_penalty": 0,
    "stop": ["Human:", "AI:"],
    "provider": "Copilot",
    "proxy": "http://proxy.example.com:8080",
    "response_format": {"type": "json_object"},
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get weather information",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string"}
                    },
                    "required": ["location"]
                }
            }
        }
    ]
}

Parameters:

• model (string, required): Model to use for completion
• messages (array, required): List of message objects
• stream (boolean): Enable streaming responses
• max_tokens (integer): Maximum tokens to generate
• temperature (number): Sampling temperature (0-2)
• top_p (number): Nucleus sampling parameter
• frequency_penalty (number): Frequency penalty (-2 to 2)
• presence_penalty (number): Presence penalty (-2 to 2)
• stop (string|array): Stop sequences
• provider (string): Specific provider to use
• proxy (string): Proxy server URL
• response_format (object): Response format specification
• tools (array): Available tools/functions

Response (Non-streaming):

{
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "gpt-4o-mini",
    "provider": "Copilot",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! How can I help you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 8,
        "total_tokens": 18
    }
}

Response (Streaming):

Content-Type: text/event-stream

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":8,"total_tokens":18}}

data: [DONE]

Example Usage

cURL:

curl -X POST "http://localhost:1337/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "g4f-api-key: your-secret-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'

Python:

import openai

client = openai.OpenAI(
    api_key="your-secret-key",
    base_url="http://localhost:1337/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

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

JavaScript:

const OpenAI = require('openai');

const client = new OpenAI({
    apiKey: 'your-secret-key',
    baseURL: 'http://localhost:1337/v1'
});

async function main() {
    const response = await client.chat.completions.create({
        model: 'gpt-4o-mini',
        messages: [{ role: 'user', content: 'Hello!' }]
    });
    
    console.log(response.choices[0].message.content);
}

main();

Image Generation

POST /v1/images/generations

Generates images from text prompts.

Request Body:

{
    "prompt": "A beautiful sunset over mountains",
    "model": "dall-e-3",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url",
    "provider": "PollinationsAI"
}

Parameters:

• prompt (string, required): Text description of desired image
• model (string): Image model to use
• n (integer): Number of images to generate (1-4)
• size (string): Image dimensions
• response_format (string): "url" or "b64_json"
• provider (string): Specific provider to use

Response:

{
    "created": 1677652288,
    "data": [
        {
            "url": "https://example.com/generated-image.jpg"
        }
    ]
}

Example Usage

cURL:

curl -X POST "http://localhost:1337/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "g4f-api-key: your-secret-key" \
  -d '{
    "prompt": "A beautiful sunset",
    "model": "dall-e-3",
    "response_format": "url"
  }'

Python:

response = client.images.generate(
    prompt="A beautiful sunset over mountains",
    model="dall-e-3",
    size="1024x1024",
    response_format="url"
)

print(response.data[0].url)

Models

GET /v1/models

Lists available models.

Response:

{
    "object": "list",
    "data": [
        {
            "id": "gpt-4o",
            "object": "model",
            "created": 0,
            "owned_by": "OpenAI",
            "image": false,
            "provider": false
        },
        {
            "id": "gpt-4o-mini",
            "object": "model",
            "created": 0,
            "owned_by": "OpenAI",
            "image": false,
            "provider": false
        },
        {
            "id": "Copilot",
            "object": "model",
            "created": 0,
            "owned_by": "Microsoft",
            "image": false,
            "provider": true
        }
    ]
}

GET /v1/models/{model_name}

Get information about a specific model.

Response:

{
    "id": "gpt-4o",
    "object": "model",
    "created": 0,
    "owned_by": "OpenAI"
}

Provider-Specific Endpoints

POST /api/{provider}/chat/completions

Use a specific provider for chat completions.

Example:

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

GET /api/{provider}/models

Get models available for a specific provider.

Response:

{
    "object": "list",
    "data": [
        {
            "id": "gpt-4",
            "object": "model",
            "created": 0,
            "owned_by": "Microsoft",
            "image": false,
            "vision": true
        }
    ]
}

Providers

GET /v1/providers

Lists all available providers.

Response:

{
    "object": "list",
    "data": [
        {
            "provider": "Copilot",
            "models": ["gpt-4", "gpt-4-vision"],
            "image_models": [],
            "vision_models": ["gpt-4-vision"],
            "url": "https://copilot.microsoft.com",
            "working": true,
            "auth": false
        }
    ]
}

GET /v1/providers/{provider}

Get detailed information about a specific provider.

Response:

{
    "provider": "Copilot",
    "models": ["gpt-4", "gpt-4-vision"],
    "image_models": [],
    "vision_models": ["gpt-4-vision"],
    "url": "https://copilot.microsoft.com",
    "working": true,
    "auth": false,
    "stream": true,
    "description": "Microsoft Copilot AI assistant"
}

Audio

POST /v1/audio/transcriptions

Transcribe audio to text.

Request:

curl -X POST "http://localhost:1337/v1/audio/transcriptions" \
  -H "g4f-api-key: your-secret-key" \
  -F "file=@audio.mp3" \
  -F "model=whisper-1"

POST /v1/audio/speech

Generate speech from text.

Request Body:

{
    "model": "tts-1",
    "input": "Hello, this is a test.",
    "voice": "alloy"
}

File Upload and Media

POST /v1/upload_cookies

Upload cookie files for authentication.

Request:

curl -X POST "http://localhost:1337/v1/upload_cookies" \
  -H "g4f-api-key: your-secret-key" \
  -F "files=@cookies.json"

GET /media/{filename}

Access generated media files.

Example:

GET /media/generated-image-abc123.jpg

Advanced Features

Conversation Management

Conversation ID

Use conversation IDs to maintain context across requests:

{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "conversation_id": "conv-abc123"
}

Provider-Specific Conversations

curl -X POST "http://localhost:1337/api/Copilot/conv-123/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Continue our conversation"}]
  }'

Vision Models

Send images with text for vision-capable models:

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
                    }
                }
            ]
        }
    ]
}

Tool/Function Calling

Define and use tools in your requests:

{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What's the weather in Paris?"}],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get current weather",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string", "description": "City name"}
                    },
                    "required": ["location"]
                }
            }
        }
    ]
}

Custom Response Formats

JSON Mode

{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Generate a JSON object with user info"}],
    "response_format": {"type": "json_object"}
}

Error Handling

Error Response Format

{
    "error": {
        "message": "Model not found",
        "type": "model_not_found",
        "code": "model_not_found"
    }
}

Common HTTP Status Codes

• 200: Success
• 400: Bad Request (invalid parameters)
• 401: Unauthorized (missing or invalid API key)
• 403: Forbidden (insufficient permissions)
• 404: Not Found (model or provider not found)
• 422: Unprocessable Entity (validation error)
• 500: Internal Server Error

Error Types

Authentication Errors

{
    "error": {
        "message": "Invalid API key",
        "type": "authentication_error",
        "code": "invalid_api_key"
    }
}

Model Errors

{
    "error": {
        "message": "Model 'invalid-model' not found",
        "type": "model_not_found",
        "code": "model_not_found"
    }
}

Provider Errors

{
    "error": {
        "message": "Provider not working",
        "type": "provider_error",
        "code": "provider_not_working"
    }
}

Configuration

Environment Variables

# Set API configuration via environment
export G4F_PROXY="http://proxy.example.com:8080"
export G4F_API_KEY="your-secret-key"
export G4F_DEBUG="true"

Runtime Configuration

from g4f.api import AppConfig

# Configure at runtime
AppConfig.set_config(
    g4f_api_key="secret-key",
    provider="Copilot",
    model="gpt-4o",
    proxy="http://proxy.example.com:8080",
    timeout=300,
    ignored_providers=["SomeProvider"],
    gui=True,
    demo=False
)

Integration Examples

OpenAI Python Client

import openai

client = openai.OpenAI(
    api_key="g4f-api-key",
    base_url="http://localhost:1337/v1"
)

# Standard usage
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Streaming
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

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

LangChain Integration

from langchain.chat_models import ChatOpenAI
from langchain.schema import HumanMessage

llm = ChatOpenAI(
    openai_api_base="http://localhost:1337/v1",
    openai_api_key="g4f-api-key",
    model_name="gpt-4o-mini"
)

response = llm([HumanMessage(content="Hello!")])
print(response.content)

Node.js Integration

const { Configuration, OpenAIApi } = require("openai");

const configuration = new Configuration({
    apiKey: "g4f-api-key",
    basePath: "http://localhost:1337/v1"
});

const openai = new OpenAIApi(configuration);

async function main() {
    const response = await openai.createChatCompletion({
        model: "gpt-4o-mini",
        messages: [{ role: "user", content: "Hello!" }]
    });
    
    console.log(response.data.choices[0].message.content);
}

Performance and Scaling

Rate Limiting

G4F API doesn't implement built-in rate limiting, but you can add it using:

from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded
from fastapi import Request

limiter = Limiter(key_func=get_remote_address)

@app.middleware("http")
async def rate_limit_middleware(request: Request, call_next):
    # Custom rate limiting logic
    pass

Caching

Implement response caching for improved performance:

from functools import lru_cache
import hashlib

@lru_cache(maxsize=1000)
def get_cached_response(request_hash):
    # Cache implementation
    pass

Load Balancing

Use multiple G4F instances behind a load balancer:

# docker-compose.yml
version: '3.8'
services:
  g4f-1:
    image: hlohaus789/g4f
    ports:
      - "1337:1337"
  g4f-2:
    image: hlohaus789/g4f
    ports:
      - "1338:1337"
  nginx:
    image: nginx
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

Security Considerations

API Key Management

import secrets

# Generate secure API key
api_key = secrets.token_urlsafe(32)

# Validate API key format
def is_valid_api_key(key):
    return len(key) >= 32 and key.isalnum()

Input Validation

The API automatically validates:

• Message format and structure
• Model name validity
• Parameter ranges and types
• File upload security

CORS Configuration

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

Monitoring and Logging

Enable Debug Logging

g4f api --debug

Custom Logging

import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger("g4f.api")

Health Checks

# Check API health
curl http://localhost:1337/v1/models

Deployment

Docker Deployment

FROM hlohaus789/g4f:latest

# Set environment variables
ENV G4F_API_KEY=your-secret-key
ENV G4F_DEBUG=false

# Expose port
EXPOSE 1337

# Start API
CMD ["python", "-m", "g4f.cli", "api", "--host", "0.0.0.0", "--port", "1337"]

Production Deployment

# Install production dependencies
pip install gunicorn uvloop

# Run with Gunicorn
gunicorn g4f.api:create_app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:1337 \
  --access-logfile - \
  --error-logfile -

This comprehensive REST API documentation covers all aspects of using G4F's API endpoints. The API is designed to be fully compatible with OpenAI's API, making it easy to integrate with existing tools and workflows.