GPT4Free (abbreviated g4f) is a community-driven project that makes using modern large language models and media generation models simpler and more flexible by aggregating multiple accessible providers and interfaces. The project offers multi-provider support, a local GUI, an OpenAI-compatible REST API, and convenient Python and JavaScript clients, under a community-first license. Created by @xtekky, maintained by @hlohaus.
I. Main Content The project includes: a Python client library and asynchronous client; an optional local Web GUI; a FastAPI-based OpenAI-compatible API (Interference API); an official browser JS client (distributed via g4f.dev); Docker images (full and slim versions); multi-provider adapters (large language models, media providers, local inference backends); and tools for image/audio/video generation and media persistence.
II. Environment Requirements and Compatibility Python 3.10+ is recommended; some providers that use browser automation require Google Chrome/Chromium; containerized deployment requires Docker; supports x86_64 and arm64 (the slim image supports both); some provider adapters may require specific platform tools (such as Chrome/Chromium), and details must be checked in the provider documentation.
III. Installation Methods
- Docker (recommended): after installing Docker, create persistent directories (example: mkdir -p ${PWD}/har_and_cookies ${PWD}/generated_media, and run sudo chown -R 1200:1201 ${PWD}/har_and_cookies ${PWD}/generated_media), pull the image docker pull hlohaus789/g4f, run the container 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. Port 8080 provides the GUI/API, and 7900 optionally exposes a VNC-like desktop for provider login; heavier browser automation tasks require increasing --shm-size.
- Slim Docker image (x64 and arm64): at startup, the g4f package can be updated and additional dependencies installed as needed; in the documentation example, the Interference API is mapped to 1337.
- Windows (.exe): a Windows launcher is provided https://github.com/gpt4free/g4f.exe；从 https://github.com/xtekky/gpt4free/releases/latest Download g4f.exe.zip, extract it and run g4f.exe, then in http://localhost:8080/chat/ open the GUI; if blocked by Windows Firewall, allow the application.
- Python installation (pip / source / partial installation): requires Python 3.10+ and Chrome/Chromium, which some providers need. Installing from PyPI is recommended; you can also install only specific features (using optional extras groups, see the project documentation docs/requirements.md); or install from source. Some features require Chrome/Chromium or other tools, and provider-specific documentation must be followed.
IV. Running the Application It can be run via Python, opening http://localhost:8080/chat/；可启动 FastAPI server; if using the slim docker mapping, the Interference API may be located at http://localhost:1337/v1，Swagger UI is located at http://localhost:1337/docs；也可启动 GUI server.
The project also includes a Model Context Protocol (MCP) server, allowing AI assistants such as Claude to access web search, scraping, and image generation capabilities. Start the MCP server (stdio mode or HTTP mode); HTTP mode provides POST http://localhost:8765/mcp（JSON-RPC endpoint) and GET http://localhost:8765/health（健康检查）。可通过 claude_desktop_config.json configuration to Claude Desktop. Available MCP tools include: web_search (search the web using DuckDuckGo), web_scrape (extract text content from web pages), image_generation (generate images from text prompts). For detailed MCP documentation, see g4f/mcp/README.md.
Optional provider login (desktop inside the container) can be done via http://localhost:7900/?autoconnect=1&resize=scale&password=secret Access, used to log in to web-based providers to obtain cookies/HAR files.
V. Client Usage The Python client supports synchronous text examples, image generation examples, and asynchronous client examples; for the complete API reference (streaming, tool calling patterns, and advanced options), see https://g4f.dev/docs/client。官方 The JS client can be used directly in the browser without a backend, distributed via the g4f.dev CDN, and attention must be paid to CORS and usage limits.
VI. Providers and Models GPT4Free integrates many providers, including (but not limited to) OpenAI-compatible endpoints, PerplexityLabs, Gemini, MetaAI, Pollinations (media), and local inference backends. Model availability and behavior depend on provider capabilities; for the currently supported provider/model list, see https://g4f.dev/docs/providers-and-models . Provider requirements may include: API keys or tokens (authentication-based providers), browser cookies/HAR files (providers scraped through browser automation), Chrome/Chromium or headless browser tools, local model binaries and runtimes (local inference).
VII. Local Inference and Media GPT4Free supports local inference backends; for supported runtimes and hardware guidelines, see docs/local.md. Media generation such as images, audio, and video is supported through providers (such as Pollinations); for formats, options, and examples, see docs/media.md.
VIII. Configuration and Customization Configuration can be done through environment variables, CLI flags, or configuration files, see docs/config.md. To reduce installation size, partial dependency groups can be used, see docs/requirements.md. Provider selection: default settings and per-request overrides are described in docs/selecting_a_provider.md. Persistence: HAR files, cookies, and generated media are saved in mapped directories (such as har_and_cookies, generated_media).
IX. Mobile and API The Web GUI is responsive and can be accessed from a phone via the host IP:8080 or through a tunnel, see docs/guides/phone.md. The Interference API supports OpenAI-like workflows and routes through GPT4Free provider selection; for documentation, see docs/interference-api.md, and the default endpoint (minimal docker example) is http://localhost:1337/v1。流式补全、停止条件、系统消息与工具调用模式见 docs/client.md, docs/async_client.md, docs/requests.md. For integrations (LangChain, PydanticAI), see docs/pydantic_ai.md; for legacy examples, see docs/legacy.md.
X. Contribution and Security Contributions of new providers, features, documentation, and fixes are welcome. Process: Fork the repository, create a branch, run tests and linter, and submit a Pull Request with a clear description and tests/examples. For a guide to creating providers, see docs/guides/create_provider.md; typical steps: implement the provider adapter in g4f/Provider/, add configuration and dependency notes, include tests and usage examples, comply with third-party code licenses and provide appropriate attribution. For workflows on writing code with AI assistance, see docs/guides/help_me.md. Do not store or share sensitive credentials, and adopt the security practices recommended by each provider. If a website appears in the project links and you wish to have it removed, you may contact https://g4f.dev/community Sending proof of ownership will result in timely removal. The production environment should use HTTPS, authentication, and firewall rules to protect the server and restrict access to provider credentials and cookie/HAR storage.
XI. License and Attribution This project is licensed under the GNU General Public License v3.0 (GPLv3) and may be redistributed and/or modified under the terms of GPLv3, with no warranty provided. Core creators: @xtekky (original author), maintained by @hlohaus. Code inputs and attributions include: har_file.py (from xqdoo00o/ChatGPT-to-API), PerplexityLabs.py (from nathanrchn/perplexityai), Gemini.py (from dsdanielpark/Gemini-API and HanaokaYuzu/Gemini-API), MetaAI.py (inspired by Strvm's meta-ai-api), proofofwork.py (from missuo/FreeGPT35). Powered-by highlights include Pollinations AI (generative media) and MoneyPrinter V2 (an example project using GPT4Free).
XII. Related Links Website and documentation:https://g4f.dev 、https://g4f.dev/docs ；PyPI：https://pypi.org/project/g4f ; Docker image:https://hub.docker.com/r/hlohaus789/g4f ; Releases:https://github.com/xtekky/gpt4free/releases ; Issue feedback:https://github.com/xtekky/gpt4free/issues ; Community: Telegram (https://telegram.me/g4f_channel）、Discord News（https://discord.gg/5E39JUWUFa）、Discord Support（https://discord.gg/qXA4Wf4Fsm）。
