💡 Like this project? ⭐️ Star the repo to support ongoing updates and help others discover it!

📖 Table of Contents

• 🎯 What is this?
• ✨ What's New in v2.0
• 🚀 Quick Start
• 📂 Repository Structure
• ⚙️ How It Works
• 🔧 Configuration
• 📦 Using as a Python Library
• 🧪 Testing
• 📊 Output File Formats
• 🤝 Contributing
• ❓ FAQ
• 📜 License
• 🌐 Links

🎯 What is this?

g4f-working is the ultimate, constantly-updated hub for discovering which AI providers and models from @xtekky/gpt4free are working right now — and, crucially, which ones require NO API keys, tokens or cookies.

Skip the hassle of trial-and-error. Every day, this project:

• 🔄 Spins up a fresh g4f API server.
• 🔍 Enumerates every provider and every model g4f knows about (typically 70+ providers, 3,000+ models).
• 🧪 Sends a real test request to each provider|model pair for text, image, audio, and video capabilities.
• 📝 Publishes the list of working ones as plain-text files you can fetch with curl or wget.

No Python needed. No dependencies. No API keys. Just grab the result files.

✨ What's New in v2.0

The codebase has been refactored from a single 1,160-line file into a clean, modular Python package. All output file names and formats are 100% backwards-compatible — your existing automation will keep working unchanged.

🐛 Bugs fixed

| # | Bug | Fix | |---|-----|-----| | 1 | testvideogeneration / testaudiogeneration mutated the payload dict across endpoint attempts, so the second endpoint received the wrong body. | Each endpoint now builds its own fresh payload. | | 2 | If the first endpoint returned HTTP 200 but had no media in the body, the tester gave up instead of trying the fallback endpoint. | Now continues to the next endpoint before reporting failure. | | 3 | responsetime was measured inconsistently — sometimes from request start, sometimes from the outer try. | Uniformly measured from starttime at the top of each test. | | 4 | startg4fapi_server used a fixed time.sleep(5) to wait for readiness — flaky on slow CI. | Now polls the server's /v1/providers endpoint until it responds 2xx or times out. | | 5 | signal.signal() was called at module import time, breaking library use. | Moved to an idempotent installsignalhooks() helper that's safe to call from any thread. | | 6 | TestResult dataclass was defined but never used (dead code). | Removed; only TestResultWithTypes is used. | | 7 | Six duplicated saveimage / savevideo / saveaudio* methods. | Consolidated into one MediaSaver class with a clean public API. | | 8 | fetchprovidersandmodels and fetchprovidersandmodelswithtypes were near-duplicates. | Merged into one parameterised fetch(with_types=...) method. | | 9 | responsetypes: List[str] = None with postinit mutation. | Replaced with field(default_factory=lambda: ["text"]). | | 10 | logging.basicConfig was called inside init every time the class was instantiated. | Now called once in main(). |

✨ New features

• 🎛️ Full CLI — every setting is overridable via --port, --timeout, --batch-size, etc.
• 🌍 Environment variables — G4FPORT, G4FAPIKEY, G4FTIMEOUT, G4FNOSERVER, …
• 🔌 Reusable as a library — import from g4f_tester import Config, run and call from your own code.
• 🧪 Comprehensive test suite — 76 unit tests covering every module, including the bug-fixes above.
• 📦 Modular package — clear separation of concerns across 8 focused modules.
• 🛡️ Safer cleanup — cleanup_browsers() is now fully idempotent and never raises.

🚀 Quick Start

For end users (just want the working list)

Nothing to install. Just fetch the raw files:

# Plain list of working models:
curl -sL https://raw.githubusercontent.com/maruf009sultan/g4f-working/refs/heads/main/working/models.txt
Provider | Model | Type lines:
curl -sL https://raw.githubusercontent.com/maruf009sultan/g4f-working/refs/heads/main/working/working_results.txt

Example output:

Blackbox|gpt-4o-mini|text BlackForestLabs_Flux1Dev|flux-dev|image DuckDuckGo|gpt-4o-mini|text HuggingSpace|command-r-08-2024|text ...

For developers (want to run the tests yourself)

git clone https://github.com/maruf009sultan/g4f-working.git
cd g4f-working
Install dependencies (system + Python)
sudo apt-get install -y ffmpeg flac          # macOS: brew install ffmpeg flac
pip install -r requirements.txt
Run the full pipeline (starts g4f API server, fetches, tests, reports)
python provider_tester.py

Common CLI overrides

# Use a different port
python provider_tester.py --port 9000
Longer timeout for slow networks
python provider_tester.py --timeout 180
Smaller batches to be gentle on the API
python provider_tester.py --batch-size 10 --max-concurrent 25
Use an already-running g4f server elsewhere
python provider_tester.py --no-server --base-url http://10.0.0.5:8081
Custom test prompts
python provider_tester.py \
  --test-message "Ping: please reply with 'pong'." \
  --image-prompt "a watercolour painting of a fox" \
  --audio-prompt "Hi, this is a TTS test."

📂 Repository Structure

g4f-working/
├── providertester.py         # 🚪 Entry point (thin wrapper around the g4ftester package)
├── g4f_tester/                # 📦 The modular Python package (v2.0)
│   ├── init.py            #    Public API exports
│   ├── models.py              #    TestResult / TestResultWithTypes dataclasses
│   ├── config.py              #    Config dataclass + CLI arg parser + env-var loader
│   ├── server.py              #    g4f API server lifecycle + nodriver cleanup
│   ├── fetcher.py             #    ProviderModelFetcher — discovers providers & models
│   ├── tester.py              #    ProviderModelTester — probes text/image/audio/video
│   ├── media_saver.py         #    MediaSaver — saves text/image/video/audio to disk
│   ├── reporter.py            #    TestResultsReporter — writes the 4 result files
│   └── runner.py              #    Orchestration + main() + legacy facade class
├── tests/                     # 🧪 76 unit tests (no network needed)
│   ├── test_models.py
│   ├── test_config.py
│   ├── test_server.py
│   ├── testmediasaver.py
│   ├── test_fetcher.py
│   ├── test_tester.py
│   ├── test_reporter.py
│   ├── test_facade.py
│   ├── run_tests.py           #    Standalone runner (no pytest required)
│   ├── smoketestreal.py     #    End-to-end test against a real g4f server
│   └── smoke_positive.py      #    Verifies a known-working provider succeeds
├── provider/                  # 📁 Daily output: provider/model discovery
│   ├── providers_models.json  #    Structured provider → models mapping
│   ├── providers_models.txt   #    Human-readable version of the above
│   └── modelsfortesting.txt #    provider|model pairs (one per line)
├── working/                   # 📁 Daily output: test results
│   ├── test_results.json      #    Full structured report (summary + working + non-working)
│   ├── test_results.txt       #    Human-readable version of the above
│   ├── working_results.txt    #    provider|model|type for every working entry
│   └── models.txt             #    Unique model (type) lines
├── output/                    # 📁 Daily output: raw model responses (text/image/audio/video)
├── generated_media/           # 📁 Audio recordings from successful TTS tests
├── .github/workflows/main.yml # ⏰ GitHub Actions: runs daily at 06:00 UTC
├── requirements.txt           # 📦 Python dependencies
├── pytest.ini                 # ⚙️ Pytest configuration
├── LICENSE.md                 # 📜 CC BY-NC 4.0
└── README.md                  # 📘 You are here

⚙️ How It Works

flowchart LR
  A[g4f API server] --> B[Fetch providers]
  B --> C[Fetch models per provider]
  C --> D[For each provider|model pair]
  D --> E{Detect capabilities}
  E -->|text| F[Test chat/completions]
  E -->|image| G[Test images/generate]
  E -->|audio| H[Test audio/speech]
  E -->|video| I[Test video/generate]
  F --> J[Save response to output/]
  G --> J
  H --> J
  I --> J
  J --> K[Aggregate results]
  K --> L[Write working/ files]
  L --> M[Commit & push]
  M -->|daily 06:00 UTC| A

• Scan — Enumerate every provider and model from g4f.
• Probe — For each provider|model pair, send a tiny test request for each capability the model advertises (text, image, audio, video).
• Persist — Save the raw response (text file / image / audio / video) to /output/.
• Aggregate — Write workingresults.txt, models.txt, testresults.json, and test_results.txt to /working/.
• Commit — The GitHub Action commits the new files back to main.
• Repeat — The cron schedule triggers again at 06:00 UTC the next day.

🔧 Configuration

Every aspect of the pipeline is configurable via CLI flags, environment variables, or Python constructor args. Priority: CLI > env vars > defaults.

| Setting | CLI flag | Env var | Default | |---------------------|-----------------------|------------------------|--------------------------------------| | g4f API base URL | --base-url | G4FBASEURL | http://localhost:8081 | | g4f API key | --api-key | G4FAPIKEY | 1234 | | g4f server port | --port | G4F_PORT | 8081 | | Max concurrent reqs | --max-concurrent | G4FMAXCONCURRENT | 50 | | Per-request timeout | --timeout | G4F_TIMEOUT | 120 (seconds) | | Test batch size | --batch-size | G4FBATCHSIZE | 20 | | Provider output dir | --provider-dir | — | provider | | Working output dir | --working-dir | — | working | | Raw output dir | --output-dir | — | output | | Skip server start | --no-server | G4FNOSERVER=1 | false (server starts) | | Text test prompt | --test-message | G4FTESTMESSAGE | Hello, are you working? ... | | Image test prompt | --image-prompt | G4FIMAGEPROMPT | a simple test image of a red apple | | Video test prompt | --video-prompt | G4FVIDEOPROMPT | a simple test video of a cat walking | | Audio test prompt | --audio-prompt | G4FAUDIOPROMPT | Hello, this is a test audio generation |

Run python provider_tester.py --help to see all options.

📦 Using as a Python Library

The new modular design means you can reuse individual pieces in your own projects:

Run the full pipeline programmatically

import asyncio
from g4f_tester import Config, run
cfg = Config.fromenv()  # reads G4F* env vars asyncio.run(run(cfg))

Fetch the current provider/model list

from g4f_tester import ProviderModelFetcher
fetcher = ProviderModelFetcher("http://localhost:8081", api_key="1234") data = fetcher.fetch()  # → {"Blackbox": {"models": [...], ...}, ...}

Test a specific provider/model

import aiohttp, asyncio
from g4f_tester import ProviderModelTester
async def main():     tester = ProviderModelTester(         base_url="http://localhost:8081",         api_key="1234",         outputdir="./myoutputs",     )     async with aiohttp.ClientSession() as session:         results = await tester.testprovidermodel_combination(             session, "BlackForestLabs_Flux1Dev", "flux-dev"         )     for r in results:         print(f"{r.mediatype}: working={r.working} time={r.responsetime:.2f}s")
asyncio.run(main())

Save media responses to disk

import asyncio
from g4f_tester import MediaSaver
async def main():     saver = MediaSaver("./outputs", base_url="http://localhost:8081")     # Save from a URL:     await saver.saveimageurl("Prov", "model", "https://example.com/img.jpg")     # Save from a base64 data URL:     await saver.saveaudiodata_url("Prov", "model", "data:audio/mp3;base64,AAAA")     # Save raw bytes:     await saver.saveaudiobytes("Prov", "model", b"\x00\x01\x02...")
asyncio.run(main())

Backwards compatibility

Existing user scripts keep working unchanged:

# This still works exactly as before:
from provider_tester import ProviderModelFetcherAndTester
tester = ProviderModelFetcherAndTester(     "http://localhost:8081", "1234",     max_concurrent=50, timeout=120, ) data = tester.fetchprovidersand_models() tester.savetofiles(data) tester.createtestformat(data) 
...etc

🧪 Testing

Run the unit tests (no network required)

# Option A: use the standalone runner (no pytest needed)
python tests/run_tests.py
Option B: use pytest
python -m pytest tests/ -v

Expected output:

======================================== TOTAL: 76 passed, 0 failed ========================================

The unit tests use mocks for the HTTP layer, so they're fast (~3 seconds) and don't need a real g4f server.

Run the end-to-end smoke tests (requires network + g4f installed)

# Spins up a real g4f API server, fetches providers, tests 3 pairs.
python tests/smoketestreal.py
Finds a known-working provider and verifies it actually produces output.
python tests/smoke_positive.py

What's covered

| Test file | What it verifies | |----------------------|--------------------------------------------------------------------| | testmodels.py | Dataclass defaults, responsetypes mutation safety, to_dict(). | | test_config.py | CLI parser, env-var loading, dir creation, header building. | | test_server.py | TCP-port probing, server-readiness polling, idempotent hooks. | | testmediasaver.py| Text/bytes/URL/data-URL saving, filename safety, error recovery. | | test_fetcher.py | Provider/model discovery, JSON+TXT output formats, error handling.| | test_tester.py | Streaming responses, payload-isolation bugfix, endpoint fallback. | | test_reporter.py | All 4 output files, deduplication, empty-result handling. | | test_facade.py | Backwards-compatible API surface for legacy users. |

📊 Output File Formats

⚠️ These formats are part of the public contract. Many users fetch them via raw.githubusercontent.com URLs — do not change them without bumping the major version.

working/models.txt

Plain list of working models (deduplicated), one per line, in the format model (type):

gpt-4o-mini (text)
flux-dev (image)
tts-1 (audio)
sora-2 (video)

working/working_results.txt

One line per working provider|model|type triple:

Blackbox|gpt-4o-mini|text
BlackForestLabs_Flux1Dev|flux-dev|image
Openai|tts-1|audio

working/test_results.json

Structured report with summary, working models (with response previews), and non-working models (with errors). Suitable for programmatic consumption.

working/test_results.txt

Human-readable summary: total tested, working count, success rate, average response time, response-type breakdown, working models grouped by type, and a list of non-working models with their errors.

provider/providers_models.json + .txt

Full provider → models mapping. The JSON is the canonical structured form; the TXT is a pretty-printed human-readable version.

provider/modelsfortesting.txt

All provider|model pairs, one per line, prefixed by a # Format: comment. Used by external automation tools to know what was tested.

output/<Provider><Model>*.{txt,jpg,mp3,mp4}

Raw responses from each test. Filenames are constructed by replacing / and \ in the model name with , then appending response.txt, imageN.jpg, audio.mp3, or video.mp4.

🤝 Contributing

Pull requests, issues, and suggestions are welcome! Please:

• 🍴 Fork the repo and create a feature branch.
• ✅ Run python tests/run_tests.py before submitting — all 76 tests must pass.
• 📝 Update the relevant section of this README if you change user-facing behaviour.
• 🎯 Keep output file formats backwards-compatible (or bump the major version if you must break them).
• 📜 Check LICENSE.md before contributing — this project is CC BY-NC 4.0 (non-commercial).

Local development tips

# Run a single test file:
python tests/runtests.py models          # tests/testmodels.py
Run with verbose pytest output:
python -m pytest tests/test_tester.py -v
Quick syntax check on all modules:
python -c "import ast, os; [ast.parse(open(os.path.join(r,f)).read()) for r,,fs in os.walk('g4ftester') for f in fs if f.endswith('.py')]; print('All OK')"

❓ FAQ

curl -sL https://raw.githubusercontent.com/maruf009sultan/g4f-working/refs/heads/main/working/models.txt

<audio controls src="/media/1754290396_gpt-4o-mini-audio-preview.mp3"></audio>

📜 License

This project is licensed under Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) — see LICENSE.md.

In plain English:

• ✅ Share and adapt the code
• ✅ Use it for personal and academic projects
• ❌ No commercial use without permission
• ✅ Attribution required

🌐 Links

• 📦 @xtekky/gpt4free — the upstream project this repository tests against.
• 📄 Latest models.txt — plain list of working models.
• 📄 Latest working_results.txt — provider|model|type triples.
• 📊 Latest test_results.json — full structured report.
• ⏰ GitHub Actions workflow — see the daily run history.