Developer docs / AI Fabric tutorials

Stable Diffusion API (CLI + web)

  • GPU
  • Volume
  • Web endpoint
  • Image DSL

Most image-generation code gets written twice: once as a script you run from the terminal, and again as an HTTP service behind a frontend. With AI Fabric you don't have to choose. One decorated function can be both, a CLI tool and a web endpoint, because @app.web_endpoint and @app.local_entrypoint are two doors into the same code.

In this tutorial you'll serve Stable Diffusion 1.5 on a GPU, drive it from the command line for quick experiments, then deploy the exact same function as a curl-able URL. Weights live on a Volume so cold starts only bite once, and the endpoint scales to zero so it costs nothing while idle.

Before you start

You need the AI Fabric CLI installed and authenticated: run blade setup once. The function asks for a single RTX A4500 and builds on fabric/torch, the catalog image that already ships CUDA and PyTorch, so there's nothing to build by hand.

Create the app and a weights Volume

Create a file called sd_api.py. Add the App and a Volume, storage that survives across runs. SD 1.5's weights download into it the first time and are read straight back afterwards, so neither the CLI nor the endpoint pays for the download twice.

sd_api.py
import bladekit
import io

app = bladekit.app("sd-api")

hf_cache = bladekit.Volume.from_name("hf-cache", create_if_missing=True)

Define the image

Layer the diffusion stack onto the fabric/torch base. The .env(...) call points HF_HOME at the Volume mount, so Hugging Face writes the downloaded weights into /hf-cache rather than an ephemeral directory that vanishes when the container stops.

Python
image = (
    bladekit.Image.from_catalog("fabric/torch")
    .pip_install("torch", "diffusers", "transformers", "accelerate", "safetensors")
    .env({"HF_HOME": "/hf-cache"})
)

Write the endpoint function

Stack two decorators on the function. @app.web_endpoint(methods=["POST"], ...) exposes it over HTTP and sets the replica bounds, and @app.function(...) asks for the GPU, the image, and the Volume. Because it's a web handler it receives the parsed request body (a dict) as its first argument, and the _pipe global keeps the model resident across calls.

Python
_pipe = None

@app.web_endpoint(methods=["POST"], min_replicas=0, max_replicas=2)
@app.function(gpu="RTX-A4500", image=image, timeout=600, volumes={"/hf-cache": hf_cache})
def generate(item: dict) -> bytes:
    global _pipe
    import torch
    from diffusers import StableDiffusionPipeline

    if _pipe is None:
        _pipe = StableDiffusionPipeline.from_pretrained(
            "runwayml/stable-diffusion-v1-5",
            torch_dtype=torch.float16,
        ).to("cuda")

min_replicas=0 is what makes the endpoint scale to zero: when no one is calling it idles all the way down and costs nothing. The first request after an idle period reloads the pipeline (the cold start), and max_replicas=2 lets AI Fabric add a second replica when traffic warrants it.

Read the request and render

Pull prompt and steps out of the request dict with sensible defaults, so a bare {} still produces an image. Generate, encode to PNG in memory, and return the raw bytes as the response body.

Python
    prompt = item.get("prompt", "a serene mountain landscape")
    steps = item.get("steps", 20)
    result = _pipe(prompt, num_inference_steps=steps)
    buf = io.BytesIO()
    result.images[0].save(buf, format="PNG")
    return buf.getvalue()

Add the CLI entrypoint

The second door. A local_entrypoint runs on your laptop and calls the same generate function with .remote(...). It reads the prompt from the command line (note that it passes a dict, exactly the shape the web handler expects) and writes the returned PNG to disk.

Python
@app.local_entrypoint()
def main():
    import pathlib, sys
    prompt = " ".join(sys.argv[1:]) or "a cat riding a bicycle"
    png = generate.remote({"prompt": prompt})
    out = pathlib.Path("sd-out.png")
    out.write_bytes(png)
    print(f"Saved {out} ({len(png) / 1e3:.0f} KB)")

Run it as a CLI tool

Everything after -- is forwarded to your entrypoint's sys.argv, so you can pass a prompt straight on the command line:

Terminal
blade run sd_api.py -- a cat in a spacesuit

The first run downloads the SD 1.5 weights into the Volume; runs after that start much faster because the bytes are already cached. Your image lands at sd-out.png.

Deploy it as a web API

Same function, second interface. Deploy the app to get a stable HTTPS URL, then POST a prompt and save the PNG response. Endpoints are private by default, so the call carries your AI Fabric token as a bearer credential.

Terminal
blade deploy sd_api.py

Terminal
curl -X POST <URL> -H 'Authorization: Bearer <FABRIC_TOKEN>' -d '{"prompt": "cyberpunk cityscape"}' -o out.png

That's one piece of model code serving both a terminal workflow and an HTTP API. With min_replicas=0 the deployed endpoint idles down to nothing between requests, so you only pay for the GPU while it is generating.

Take it for a spin

Everything above in one file, ready to run.

sd_api.py
import bladekit
import io

app = bladekit.app("sd-api")

hf_cache = bladekit.Volume.from_name("hf-cache", create_if_missing=True)

image = (
    bladekit.Image.from_catalog("fabric/torch")
    .pip_install("torch", "diffusers", "transformers", "accelerate", "safetensors")
    .env({"HF_HOME": "/hf-cache"})
)

_pipe = None

@app.web_endpoint(methods=["POST"], min_replicas=0, max_replicas=2)
@app.function(gpu="RTX-A4500", image=image, timeout=600, volumes={"/hf-cache": hf_cache})
def generate(item: dict) -> bytes:
    global _pipe
    import torch
    from diffusers import StableDiffusionPipeline

    if _pipe is None:
        _pipe = StableDiffusionPipeline.from_pretrained(
            "runwayml/stable-diffusion-v1-5",
            torch_dtype=torch.float16,
        ).to("cuda")

    prompt = item.get("prompt", "a serene mountain landscape")
    steps = item.get("steps", 20)
    result = _pipe(prompt, num_inference_steps=steps)
    buf = io.BytesIO()
    result.images[0].save(buf, format="PNG")
    return buf.getvalue()

@app.local_entrypoint()
def main():
    import pathlib, sys
    prompt = " ".join(sys.argv[1:]) or "a cat riding a bicycle"
    png = generate.remote({"prompt": prompt})
    out = pathlib.Path("sd-out.png")
    out.write_bytes(png)
    print(f"Saved {out} ({len(png) / 1e3:.0f} KB)")

Concepts used: Cold start, Endpoint, Scale-to-zero, GPU

Contact the team

Loading the form…