Download the PHP package minhyung/sdwebui without Composer

minhyung/sdwebui

A fluent PHP SDK for the Stable Diffusion WebUI API.

Built on PSR interfaces only — no HTTP client is bundled or required. If you do not inject one, it is discovered from whatever your project already has.

Requirements

• PHP 8.2+, with ext-json and ext-mbstring
• A WebUI started with --api

Installation

This package deliberately bundles no HTTP client, so you must supply one. Install it alongside:

or, with Guzzle:

composer require minhyung/sdwebui on its own is not enough. It will install cleanly — php-http/discovery satisfies the PSR implementation requirements on paper — but the first call then fails with a ConfigurationException, because there is no actual client to discover.

Already set up? A bare composer require minhyung/sdwebui is fine if the project has both a PSR-18 client and a PSR-7/17 implementation. Those are two separate things, and some packages only bring one:

Timeouts — read this first

PSR-18 has no concept of a timeout, so this SDK cannot set one. Generation runs synchronously on the server behind a lock, and a large batch or a slow model takes minutes. With a default client timeout of 30 seconds, your requests will fail long before the image is ready.

Inject a client configured for it:

Authentication

For a server started with --api-auth user:pass:

Two things worth knowing:

• The server parses --api-auth by splitting on , then :, so a password containing either character cannot be configured server-side at all.
• --gradio-auth does not protect /sdapi/v1/*, and a few extension-registered routes (the LoRA listing among them) bypass --api-auth entirely. Do not treat the API as protected just because one of those flags is set.

Generating images

txt2img

Enums are a convenience, never a constraint — every setter that takes one also takes a plain string, so sampler names added by extensions keep working. Ask the server what it actually has with $sd->catalog()->samplerNames().

Hires fix

img2img and inpainting

Per-request settings

Convenient, but slow in bulk: the server reloads the model and unloads it again on every request. Generating many images against one checkpoint is much faster if you set it once:

Images

Image handles the encoding so you do not have to:

Response images are not necessarily PNG — the server encodes them according to its samples_format setting. extension() and mimeType() reflect what actually arrived.

Postprocessing

Reading metadata

The server restores only the fields the WebUI tags for the API, which is fewer than an infotext contains. On txt2img that covers the prompts, size, CFG scale, batch size, styles, denoising strength, the hires-fix block, steps, sampler, scheduler, seed and the refiner. On img2img the tab's own fields are untagged, so denoising_strength, inpainting_fill, inpaint_full_res, cfg_scale and the size are not restored there — set them yourself. Anything you set explicitly always wins over the infotext.

If the server answers HTTP 500 ... cannot be used with isinstance(), it types one of those fields as Any, which makes its own restore step raise before it applies anything. Setting the field explicitly makes the server skip it. On Forge Neo the field is styles:

Extensions

ControlNet and ADetailer have typed helpers:

Call controlNet() more than once for multi-unit setups.

These helpers are best-effort. Argument layouts belong to the installed version of each extension, and the server silently discards arguments it does not expect — a wrong layout produces an image that quietly ignored your settings rather than an error. When something has no effect, check what the instance actually declares:

Any script can be driven directly:

Progress

Generation blocks until it finishes, so progress has to be watched from somewhere else. Every request carries a task id for exactly this:

Then, from anywhere:

This is per-task, so it stays correct when several clients share an instance. $sd->progress()->current() gives the server-wide snapshot instead.

isFinished() is the only positive signal that the work is done. isUnknown() means two opposite things depending on when it arrives: before the task has ever been seen it is "not submitted yet", because the id is published ahead of send(); after it has been seen it is "gone", since the server remembers only the last 16 finished tasks. A poll loop has to end on both, plus a deadline for the first sighting — examples/progress.php has the shape.

Single-process polling

If you would rather stay in one process, onProgress() can do it — but it needs a client that both sends asynchronously and can be advanced in bounded slices, since a plain Promise::wait() would block until the image is done and defeat the purpose. Symfony\Component\HttpClient\HttplugClient qualifies, and needs all four of these:

guzzlehttp/promises is easy to miss — Symfony's HttplugClient only reports it missing at the moment of the first async send.

Clients that cannot be ticked are rejected with a clear error rather than hanging.

Inspecting the server

$sd->server()->ping() answers false for any failure, including bad credentials — it is built for a health check, where the only question is whether to route traffic. For a "test connection" screen that has to tell the user what went wrong, call something real and let the typed exceptions through instead:

examples/inspect.php summarises a running instance: its sample format, and the total count plus first 20 entries of each of its checkpoints, samplers, schedulers, upscalers, LoRAs, and always-on scripts.

Writes through $sd->options() are persistent — they are saved to the server's config.json, not scoped to your session. Use overrideSetting() on a request for per-request changes. Note also that options flagged restrict_api server-side are ignored without an error, so read back anything that matters.

Error handling

Endpoints not modelled here

Extension routes and anything newer than this SDK can go through the transport directly:

Individual request fields have an escape hatch too:

Hooking into requests

There is no middleware layer. Everything goes out through the PSR-18 client you inject, so decorate that — one implementation of sendRequest() covers retries, metrics, tracing, or an egress allowlist for every call this SDK makes:

The base URL is validated as an absolute http/https URL with a host. Credentials embedded in it are rejected — use basicAuth(), which sends them as a header rather than as part of a URI that reaches every log line — and so are a query string and a fragment, since every request path is appended to the base URL and would land inside them. Validation does not resolve the host or restrict where it points; if untrusted input can reach the base URL, do that check yourself in a decorator like the one above.

API quirks this SDK handles for you

The WebUI API has a number of sharp edges. These are absorbed so you do not have to think about them:

• info is JSON inside JSON. Generation responses carry info as an encoded string; it is decoded transparently by $result->info().
• denoising_strength has no working default on txt2img. The server's schema generator lets the base class's null overwrite the documented 0.75, so hires fix silently does nothing when it is unset. An explicit value is always sent when enable_hr is on.
• API defaults disagree with the UI. steps defaults to 50 server-side but 20 in the browser; inpainting_fill to "fill" rather than "original"; inpaint_full_res to "only masked" rather than "whole picture". The UI values are sent explicitly so results match what the same settings produce in the browser.
• Grid images. A multi-image batch prepends a contact sheet to the raw list. images() returns only the samples; grid() exposes the sheet.
• The data-URI parser is fragile. The server splits data URIs naively and corrupts anything carrying an extra parameter, so images always go out as bare base64.
• extra-batch-images uses imageList — the only camelCase key in the API, and a trap for any generic snake_case serialiser.
• Two different 422 shapes, one itemised and one not; ValidationException normalises both.
• cmd-flags leaks credentials. It returns api_auth and gradio_auth in plaintext, so this SDK never logs that response — and neither should you.

Logging

Requests and responses are logged at debug. Long strings — base64 images, mostly — are replaced with a size marker so logs stay readable, and the cmd-flags response is never logged at all.

Building that context is not free: the body is materialised, decoded, walked and re-encoded, which on a request carrying a base64 image is megabytes of work. PSR-3 offers no way to ask a logger whether debug is enabled, so injecting a framework logger configured at info would pay all of it and discard the result. Say so explicitly:

Nothing is built after that. With no logger injected at all the cost is already skipped.

Contributing

Unit tests use a mock HTTP client and never touch the network.

License

MIT. See LICENSE.