Image Batches for fal.ai

Comparing image models in the fal.ai web playground gets old fast. You paste almost the same prompt into three tabs, download files with random names, and ten minutes later you have no idea which fox came from which model or what prompt tweak actually helped. I hit that wall during a direct-to-film T-shirt printing job, where we needed a batch of design variations (different subjects and illustration styles, tested across several models) compared side by side and then cleaned up into print-ready PNGs.

So I built falg to run those batches from a single JSON config.

Instead of running prompts one by one, you describe the job once: a prompt template, a map of variables, and the models you want to test. Any variable that’s an object becomes an axis, and falg expands every combination across every model and runs the whole grid in parallel.

{
  "name": "chest-logos",
  "models": ["gpt-image-2.5", "nano-banana-2.1"],
  "aspect": "1:1",
  "template": "{subject}. Style: {style} {background}",
  "vars": {
    "subject": {
      "fox": "A cheerful red fox",
      "owl": "A tiny owl astronaut"
    },
    "style": {
      "riso": "Retro risograph print, coarse halftone dots.",
      "ink": "Bold ink line art."
    },
    "background": "On a plain pure white background. No text, no frame."
  }
}

Preview the grid first, then run it and open the gallery:

falg run chest-logos.json --only subject=fox --dry-run   # preview prompts and estimated cost
falg run chest-logos.json --only subject=fox -y          # 2 styles × 2 models, in parallel
open generations/*-chest-logos/index.html                # compare the results side by side

Because image generation costs real money, falg asks before spending by default. If there’s no terminal attached, it refuses to run unless you pass -y or a --max-cost limit. That makes it safe to hand over to a script or an AI agent without worrying about an accidental loop draining your balance. Add --json and the plan (or the finished run) comes back as JSON, with an exit code of zero only if every request succeeded.

Every downloaded image gets a .json sidecar right next to it with the expanded prompt, the variables, the model, the seed, and the exact request arguments. Nothing gets lost when you come back to a folder two weeks later. Each run also drops a self-contained index.html gallery into the output folder with prompts as rows, models as columns, and a quick toggle between grey, white, and black backgrounds so you can judge both light and dark artwork properly.

Grids aren’t the only mode. falg gen "a prompt" runs a one-off without a config, and falg edit photo.png "make the cat smile" sends an image through the models’ edit endpoints; give a config an images list and the whole grid runs as edits instead.

Model names rot fast in this space, so falg catalog keeps a dated MODELS.md of what fal has released in the last six months, with prices, and flags newer releases in the same family as each model falg already knows. On one refresh it caught GPT Image 2.6 the day after it came out.

The one piece that came straight out of the T-shirt work is falg cutout. Asking image models for a transparent background is unreliable, and mentioning “T-shirt” or “sticker” in the prompt usually tricks them into drawing a mockup of the product instead of the illustration itself. What actually works is generating on plain white or black and knocking the background out afterward. cutout uses the image as its own mask, defringes the edges so dark lines don’t keep a pale halo, crops to the artwork, and can even size the output in centimeters and check for lines too thin to hold ink. If the source image has a falg sidecar, the cutout keeps that history attached.

The core CLI uses only the Python standard library; the optional [cutout] extra brings in numpy, Pillow, and SciPy for the image processing part. Install it with pipx install 'falg[cutout]' (or uv tool install 'falg[cutout]'). The source and full documentation are on GitHub, the package on PyPI.