imgen

CLI tool to generate images via the Replicate API. Works with any image generation model on Replicate.

Default model: black-forest-labs/flux-1.1-pro

Supported models

Any Replicate model that takes a prompt and outputs an image URL works. The model version and input schema are resolved automatically via the API.

Model	Description	Speed	Text in images
black-forest-labs/flux-1.1-pro	FLUX Pro -- best quality (default)	~4s	poor
black-forest-labs/flux-1.1-pro-ultra	FLUX Ultra -- highest resolution	~6s	poor
black-forest-labs/flux-schnell	FLUX Schnell -- fast & cheap	~1s	poor
black-forest-labs/flux-dev	FLUX Dev -- open-source variant	~10s	poor
ideogram-ai/ideogram-v3-quality	Ideogram v3 -- best for text in images	~10s	excellent
stability-ai/sdxl	Stable Diffusion XL	~5s	poor
stability-ai/stable-diffusion-3	Stable Diffusion 3	~5s	moderate

Aspect ratios are handled transparently. imgen reads each model's OpenAPI schema from the API and determines whether it uses aspect_ratio or raw width/height parameters:

• custom supported (e.g. FLUX Pro): exact pixel dimensions are sent as-is.
• Fixed ratios only (e.g. 16:9, 3:4, 1:1): the closest matching ratio is selected automatically from the model's allowed values.
• No aspect_ratio parameter: width and height are passed directly.

Installation

Homebrew (macOS / Linux)

brew tap casoon/tap
brew install imgen

From source

cargo install --path .

Or build manually:

cargo build --release

Setup

Set your Replicate API token:

export REPLICATE_API_TOKEN="r8_your_token_here"

Usage

Single image

imgen "A sunset over the ocean" --out sunset.png

With custom dimensions:

imgen "A cat in space" --width 1920 --height 1080 --out cat.png

Different model

imgen "A cat in space" --model stability-ai/sdxl --out cat.png

Batch mode

The prompt file supports two formats:

Simple array (all defaults from CLI):

[
  { "prompt": "A mountain landscape", "out": "images/mountain.png" },
  { "prompt": "A cityscape at night", "out": "images/city.png" }
]

Object with defaults (shared settings for all jobs):

{
  "defaults": {
    "model": "black-forest-labs/flux-schnell",
    "width": 1024,
    "height": 1024,
    "webp": 80
  },
  "jobs": [
    {
      "prompt": "A mountain landscape at sunset",
      "out": "images/mountain.png"
    },
    {
      "prompt": "A futuristic cityscape with neon lights",
      "out": "images/city.png",
      "width": 1920,
      "height": 1080
    },
    {
      "prompt": "A coffee shop interior",
      "out": "images/coffee.png",
      "model": "stability-ai/sdxl"
    }
  ]
}

Values in individual jobs override the defaults. Defaults override CLI flags.

Run:

imgen --prompt-file prompts.json

Batch mode features:

• Progress is printed as [1/5], [2/5], … so you can track the current job.
• Output directories are created automatically if they don't exist.
• A failing job does not abort the remaining jobs -- all jobs run, and errors are reported at the end.

WebP conversion

Convert output to WebP (default quality 80):

imgen "A sunset" --out sunset.webp --webp

With custom quality (0-100):

imgen "A sunset" --out sunset.webp --webp 60

The output file always gets a .webp extension regardless of the --out value. For example, --out sunset.png --webp produces sunset.webp.

Models that support server-side format selection (e.g. flux-1.1-pro) deliver the WebP directly from the API -- no local conversion needed. For all other models, imgen converts locally using the webp crate and replaces the original file. Works in batch mode too (via defaults or per-job webp field).

All options

Usage: imgen [OPTIONS] [PROMPT]

Arguments:
  [PROMPT]  Text prompt for image generation

Options:
      --prompt-file <FILE>  JSON file with jobs
      --model <MODEL>       Replicate model (owner/name) [default: black-forest-labs/flux-1.1-pro]
      --width <WIDTH>       Output width in pixels [default: 1024]
      --height <HEIGHT>     Output height in pixels [default: 768]
      --out <OUT>           Output file path [default: output.png]
      --webp [<QUALITY>]    Convert to WebP (default quality: 80)
  -h, --help                Print help
  -V, --version             Print version

Rate limiting & timeouts

imgen handles Replicate API rate limits automatically:

• On HTTP 429 Too Many Requests, the Retry-After header is respected (fallback: 10 seconds).
• Up to 5 retries per request before giving up.
• Each image generation times out after 120 seconds of polling (poll interval: 2 seconds).

JSON schema

Defaults (optional)

Field	Type	Description
model	string	Replicate model for all jobs
width	u32	Default width for all jobs
height	u32	Default height for all jobs
webp	f32	Convert all jobs to WebP with this quality (0-100)

Jobs

Field	Type	Required	Description
prompt	string	yes	Text prompt for image generation
out	string	yes	Output file path
width	u32	no	Image width (overrides default)
height	u32	no	Image height (overrides default)
model	string	no	Replicate model (overrides default)
webp	f32	no	Convert to WebP with this quality (overrides default)

Priority

Per-job value > defaults section > CLI flags (--model, --width, --height, --webp)

License

MIT