Fooocus-API: a REST layer over Fooocus for scripted image generation

The Gradio client problem Fooocus-API was written to fix

Fooocus ships as a Gradio application. Calling it from another program means driving Gradio's client protocol, and the README is blunt about that experience: the author calls it "a terrible experience for me." That is the gap this project fills. Fooocus-API puts a FastAPI service in front of Fooocus and exposes REST endpoints, so a Python worker, a Node backend, or a shell script can request an image with an HTTP call and poll for the result. The audience is developers building something on top of Fooocus: a Discord bot, a batch renderer, an internal tool, or a pipeline that generates images as one step among others. It is not aimed at someone who wants to click through the Fooocus web UI, which already exists and works. The README states the loaded Fooocus version is 2.3.0, so the API surface tracks that release rather than the newest Fooocus commit.

How the API maps Fooocus parameters onto endpoints

The service is a Python package (fooocusapi/) started by main.py, with FastAPI and Uvicorn in requirements.txt and Pydantic pinned at 2.4.2 for request models. Two API generations are visible in the repository: examples/examples_v1.py and examples/examples_v2.py, and the README documents a V1 form-style interface alongside a V2 interface that accepts an image URL. The ImageEnhance endpoint shows the design clearly. V1 breaks the enhance controller into a flat set of prefixed keys such as enhance_input_image, enhance_uov_method, and enhance_mask_dino_prompt, with a list of enhance_ctrlnets objects capped at three elements; anything beyond that is discarded. Two fields decide whether work happens at all: enhance_checkbox must be true, and enhance_mask_dino_prompt must be non-empty, otherwise the task is skipped even when the controller is enabled. The README also notes that GenerateMask behaves like DescribeImage: neither runs as a queued task, and both return their result directly rather than through the task flow. That is a meaningful distinction when you are writing a client, because those two endpoints do not follow the same polling pattern as generation.

Installing Fooocus-API and generating a first image

The README requires Python 3.10 or newer and points to Fooocus's own minimal hardware requirements; there is no CPU-only path documented here. The conda route creates the environment from environment.yaml, then main.py starts the server on http://127.0.0.1:8888.

conda env create -f environment.yaml
conda activate fooocus-api
python main.py

On first run the README warns you may wait a while while the program finishes installation and downloads models. A venv works the same way, and the README gives platform-specific activation commands.

python -m venv venv
source venv/bin/activate
python main.py

If you prefer containers, the Dockerfile builds from pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime, exposes port 8888, and starts with flags that bind all interfaces and skip pip.

EXPOSE 8888
CMD ["python", "main.py", "--host", "0.0.0.0", "--port", "8888", "--skip-pip"]

Note the README's warning that --skip-pip should not be used after updating to Fooocus 2.5 unless you already updated dependencies manually. For a first request, the README points to examples/ and docs/api_doc_en.md as the reference for payload shapes; the enhance example above is the most fully documented body in the README itself.

Where Fooocus-API gets in your way

The dependency list is the first obstacle. requirements.txt pins torchsde, transformers 4.42.4, gradio 3.41.2, and groundingdino-py 0.4.0, among others, and the README explicitly says groundingdino-py may fail to install, particularly in Chinese Windows environments, pointing to an upstream GroundingDINO issue for the workaround. That is a real setup cost, not a footnote. Second, the project inherits Fooocus's hardware demands wholesale, so a machine that cannot run Fooocus cannot run this either. Third, the README itself carries a caution: "Although I tested it, I still suggest you test it again before the official update." That is the maintainer telling you the API can lag the upstream UI. Fourth, the README admits uncertainty about at least one parameter, enhance_uov_prompt_type, saying the function is unclear and suggesting you research it against the WebUI. If you need a documented, stable contract for every field, parts of this one are not it. Finally, if your goal is interactive exploration, this is the wrong tool: the Fooocus Gradio UI is already there, and adding an HTTP hop only makes sense when something else is calling.

Fooocus-API versus the Gradio client and ComfyUI

The obvious alternative is the Gradio client the README complains about. The difference is protocol and ergonomics: Gradio's client couples your code to the UI's component layout, so a Fooocus UI change can break your caller, while Fooocus-API gives you named REST fields and Pydantic-validated bodies. The trade-off is that you now depend on the API project keeping pace with Fooocus, which the version note (2.3.0) and the maintainer's own caution suggest is not instant. The other alternative is ComfyUI, which the repository lists as a topic. ComfyUI exposes a graph-based workflow model where you define nodes and connections; Fooocus-API exposes Fooocus's opinionated presets, where the README describes the philosophy as "the manual tweaking is not needed." If you want to control sampling internals step by step, a node graph fits better. If you want Fooocus's defaults behind an HTTP endpoint, this project is the shorter path.

Licence, releases, and the cost of keeping it current

Fooocus-API is GPL-3.0, and the repository also carries a CreativeMLOpenRAIL-M file, which is the licence family associated with the Stable Diffusion models Fooocus uses. GPL-3.0 matters if you plan to distribute a modified version or link it into a product: the copyleft terms apply to the API code, and the model licence is a separate question that governs the weights, not this repository. This is not legal advice; read both files before shipping. On maintenance, the last push to the default branch was on 2026-08-04, and the most recent tagged release is v0.5.0.1 from 2024-08-15. That gap is worth noting: the code moves, the tags do not. Upgrading is not a single command. environment.yaml and requirements.txt pin exact versions, and the README's note about Fooocus 2.5 upgrading most dependencies means a version bump can require reinstalling the environment rather than pulling new code. Budget for that, and test generation output after any update rather than assuming parity.

Editorial conclusion

Adopt Fooocus-API if you already want Fooocus quality and need to call it from a queue, a bot, or a batch script rather than a browser tab. Skip it if you only generate images by hand, or if you need a CPU-only path, since the project inherits Fooocus hardware requirements and the Dockerfile targets CUDA 12.1. Before committing, confirm the Fooocus version it pins (2.3.0 in the README) matches the features you need, and check that groundingdino-py installs cleanly on your platform, because the README flags installation errors there, especially on Chinese Windows.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. mrhan1993/Fooocus-API on GitHub
4. README
5. Releases