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.
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.
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.
_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.
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.
@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:
blade run sd_api.py -- a cat in a spacesuitThe 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.
blade deploy sd_api.pycurl -X POST <URL> -H 'Authorization: Bearer <FABRIC_TOKEN>' -d '{"prompt": "cyberpunk cityscape"}' -o out.pngThat'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.
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