---
type: open_source
id: w2vrg6k6bdc341mqhgtiikg9
title: 'Image Batches for fal.ai'
url: 'https://www.jakubpelak.com/opensource/falg'
section: projects
package: falg
repository: 'https://github.com/lemmon/falg'
---

# Image Batches for fal.ai

Comparing image models in the [fal.ai](https://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.

```json
{
  "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:

```sh
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.

> [!NOTE]
> `falg` is an unofficial community tool, not affiliated with fal.ai. It talks to fal’s public queue API using your own API key.

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](https://github.com/lemmon/falg), the package on [PyPI](https://pypi.org/project/falg/).