Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: honor width, height, steps, guidance, seed and negative_prompt on /v1/images/generations (#14351)

Daniel Hane9127c97b8a3
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 6ae93ddddaf..fe960e39595 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -5764,6 +5764,39 @@ class ImageGenerationRequest(BaseModel):
stream: Optional[bool] = Field(
None, description = "Streaming image generation is not supported; omit or set false."
)
+ width: Optional[int] = Field(
+ None,
+ ge = 256,
+ le = 2048,
+ description = "[x-unsloth] Image width in pixels (multiple of 16); send with height "
+ "instead of size.",
+ )
+ height: Optional[int] = Field(
+ None,
+ ge = 256,
+ le = 2048,
+ description = "[x-unsloth] Image height in pixels (multiple of 16); send with width "
+ "instead of size.",
+ )
+ steps: Optional[int] = Field(
+ None, ge = 1, le = 100, description = "[x-unsloth] Denoising steps (default per model)."
+ )
+ guidance: Optional[float] = Field(
+ None,
+ ge = 0.0,
+ le = 20.0,
+ description = "[x-unsloth] Classifier-free guidance scale (default per model).",
+ )
+ seed: Optional[int] = Field(
+ None,
+ ge = 0,
+ le = 2**53 - 1,
+ description = "[x-unsloth] Seed for a repeatable image (random if omitted). With n > 1 "
+ "each image derives its own seed from it.",
+ )
+ negative_prompt: Optional[str] = Field(
+ None, description = "[x-unsloth] What to avoid, on models that take a negative prompt."
+ )
@field_validator("n", "size", "response_format", mode = "before")
@classmethod
@@ -5773,6 +5806,12 @@ class ImageGenerationRequest(BaseModel):
return cls.model_fields[info.field_name].default
return value
+ @field_validator("seed", mode = "before")
+ @classmethod
+ def _minus_one_seed_means_random(cls, value):
+ # -1 = random (A1111, sd.cpp); seed was ignored here before, so -1 must not start 400ing.
+ return None if value == -1 else value
+
class ImageGenerationData(BaseModel):
"""One image in an ``ImagesResponse`` (OpenAI ``Image``). Exactly one of
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 53d5bd8e051..97cbd50856a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -53351,6 +53351,21 @@ def _parse_openai_image_size(size: str) -> tuple[int, int]:
return width, height
+def _openai_image_dims(body: ImageGenerationRequest) -> tuple[int, int]:
+ """(width, height) from ``size``, or from the width/height extension when sent. Raises
+ ValueError with a client-facing message."""
+ if body.width is None and body.height is None:
+ return _parse_openai_image_size(body.size)
+ if body.width is None or body.height is None:
+ raise ValueError("Send width and height together, or size.")
+ dims = _parse_openai_image_size(f"{body.width}x{body.height}")
+ if (body.size or "").strip().lower() not in ("", "auto") and (
+ _parse_openai_image_size(body.size) != dims
+ ):
+ raise ValueError("size and width/height disagree; send one of them.")
+ return dims
+
+
# response_format=url links must be fetchable by whoever received them: a client downloads data[].url with a plain GET
# and no Authorization header, so mint a short-lived HMAC link (1h, like OpenAI) and leave the gallery route bearer-only.
_IMAGE_LINK_TTL = 3600
@@ -53487,7 +53502,8 @@ async def openai_image_generations(
Generates ``n`` images from ``prompt`` on the loaded diffusion model and
returns them as URLs (default) or base64 PNGs per ``response_format``. Steps
- and guidance have no OpenAI knob, so they default per loaded model.
+ and guidance have no OpenAI knob: the x-unsloth fields set them (and width, height,
+ seed, negative_prompt), else they default per loaded model.
With media auto-switch on, ``model`` names the image model to serve on and is loaded
when it is not the resident one; with it off ``model`` stays informational."""
@@ -53512,7 +53528,7 @@ async def openai_image_generations(
),
)
try:
- width, height = _parse_openai_image_size(body.size)
+ width, height = _openai_image_dims(body)
except ValueError as exc:
raise HTTPException(
status_code = 400, detail = openai_error_body(str(exc), status = 400, param = "size")
@@ -53605,16 +53621,20 @@ async def _generate_openai_images(
)
steps, guidance = await asyncio.to_thread(_image_generation_defaults, status)
+ steps = steps if body.steps is None else body.steps
+ guidance = guidance if body.guidance is None else body.guidance
reset_media_generation_progress("image")
try:
with account_access.media_generation("diffusion"):
result = await asyncio.to_thread(
backend.generate,
prompt = body.prompt,
+ negative_prompt = body.negative_prompt,
width = width,
height = height,
steps = steps,
guidance = guidance,
+ seed = body.seed,
batch_size = body.n,
expected_load = load_identity(
status.get("repo_id"), status.get("base_repo"), status.get("family")
@@ -53657,7 +53677,7 @@ async def _generate_openai_images(
# Persist each image with its full recipe, like /images/generate, so url links resolve and images show in the gallery.
recipe = {
"prompt": body.prompt,
- "negative_prompt": None,
+ "negative_prompt": result.get("negative_prompt"),
"width": width,
"height": height,
"steps": steps,
diff --git a/studio/backend/tests/test_openai_images_generations_route.py b/studio/backend/tests/test_openai_images_generations_route.py
index 5eef2a4dab1..45c9e0b8bf0 100644
--- a/studio/backend/tests/test_openai_images_generations_route.py
+++ b/studio/backend/tests/test_openai_images_generations_route.py
@@ -167,6 +167,8 @@ class _FakeBackend:
guidance,
batch_size = 1,
expected_load = None,
+ seed = None,
+ negative_prompt = None,
):
if not self._loaded:
raise RuntimeError("No diffusion model is loaded.")
@@ -189,12 +191,15 @@ class _FakeBackend:
guidance = guidance,
batch_size = batch_size,
expected_load = expected_load,
+ seed = seed,
+ negative_prompt = negative_prompt,
)
)
out = {
"images": [object() for _ in range(batch_size)],
- "seed": 4242,
+ "seed": 4242 if seed is None else seed,
"repo_id": self._repo_id,
+ "negative_prompt": negative_prompt or None,
}
if self._native_seeds:
out["seeds"] = [4242 + i for i in range(batch_size)]
@@ -251,6 +256,8 @@ def test_url_response_shape(client):
guidance = 0.0,
batch_size = 1,
expected_load = load_identity("unsloth/Z-Image-Turbo-GGUF", None, "z-image"),
+ seed = None,
+ negative_prompt = None,
)
@@ -443,6 +450,90 @@ def test_validation_400_with_param(client, body, param):
assert k in err
+def test_unsloth_recipe_fields_reach_the_engine_and_the_recipe(client, monkeypatch):
+ # #14335: these keys were dropped, giving 1024x1024 at the model defaults with a random seed.
+ store = {}
+
+ def _save(image, meta):
+ store[len(store)] = meta
+ return {**meta, "id": f"img{len(store)}"}
+
+ monkeypatch.setattr(gallery_module, "save", _save)
+ resp = _post(
+ client,
+ {
+ "prompt": "Draw a simple happy face.",
+ "width": 512,
+ "height": 768,
+ "steps": 10,
+ "guidance": 2.0,
+ "seed": 42,
+ "negative_prompt": "blurry",
+ "batch_size": 1,
+ "batch_seed": 42,
+ "batch_index": 0,
+ "model": "default",
+ },
+ )
+ assert resp.status_code == 200
+ call = client.backend.calls[0]
+ assert (call["width"], call["height"], call["steps"], call["guidance"]) == (512, 768, 10, 2.0)
+ assert call["seed"] == 42 and call["negative_prompt"] == "blurry"
+ recipe = store[0]
+ assert (recipe["width"], recipe["height"], recipe["steps"], recipe["guidance"]) == (
+ 512,
+ 768,
+ 10,
+ 2.0,
+ )
+ assert recipe["seed"] == 42 and recipe["batch_seed"] == 42
+ assert recipe["negative_prompt"] == "blurry"
+
+
+def test_omitted_recipe_fields_keep_the_model_defaults(client):
+ resp = _post(client, {"prompt": "p", "steps": None, "guidance": None, "seed": None})
+ assert resp.status_code == 200
+ call = client.backend.calls[0]
+ assert (call["width"], call["height"], call["steps"], call["guidance"]) == (1024, 1024, 8, 0.0)
+ assert call["seed"] is None and call["negative_prompt"] is None
+
+
+def test_one_recipe_field_leaves_the_other_default(client):
+ assert _post(client, {"prompt": "p", "guidance": 1.5}).status_code == 200
+ assert (client.backend.calls[0]["steps"], client.backend.calls[0]["guidance"]) == (8, 1.5)
+
+
+def test_seed_minus_one_means_random(client):
+ assert _post(client, {"prompt": "p", "seed": -1}).status_code == 200
+ assert client.backend.calls[0]["seed"] is None
+
+
+def test_width_height_agreeing_with_size_is_accepted(client):
+ resp = _post(client, {"prompt": "p", "size": "512x768", "width": 512, "height": 768})
+ assert resp.status_code == 200
+ assert (client.backend.calls[0]["width"], client.backend.calls[0]["height"]) == (512, 768)
+
+
+ "extra",
+ [
+ {"width": 512}, # height missing
+ {"height": 512}, # width missing
+ {"width": 520, "height": 512}, # not a multiple of 16
+ {"width": 512, "height": 512, "size": "1024x1024"}, # disagrees with size
+ {"width": 128, "height": 512}, # below the bound
+ {"steps": 0},
+ {"guidance": 25.0},
+ {"seed": -2},
+ ],
+)
+def test_bad_recipe_fields_are_a_400_before_any_run(client, extra):
+ resp = _post(client, {"prompt": "p", **extra})
+ assert resp.status_code == 400
+ assert resp.json()["error"]["type"] == "invalid_request_error"
+ assert client.backend.calls == []
+
+
@pytest.mark.parametrize("n", [0, 11, -1])
def test_n_out_of_range_400(client, n):
resp = _post(client, {"prompt": "p", "size": "256x256", "n": n})