batch-renderer 1.7.1

CLI tool for batch rendering AI image prompts from markdown files

Batch Renderer

A CLI tool for batch rendering AI image prompts from markdown files using the Poe API.

Features

• 📝 Extract prompts from markdown files using configurable patterns
• 🎨 Batch render images using multiple AI models (GPT-Image-1, Nano-Banana, etc.)
• 📦 Nested output structure organized by sections
• 🎯 Per-prompt metadata to override model, quality, aspect ratio, etc.
• 🔄 Automatic retries on errors
• 📊 Rich CLI interface with progress bars and colored output
• ✅ Dry-run mode to preview extraction before rendering
• ⚙️ Flexible configuration via CLI, environment variables, or inline metadata

Installation

# Clone the repository
cd batch-renderer

# Install dependencies
pipenv install

# Install the package in editable mode
pipenv install -e .

Quick Start

1. Set up your Poe API key:

   echo "POE_API_KEY=your_api_key_here" >> .env
   

2. Create a markdown file with prompts (see Format below)

3. Dry run to preview:

   pipenv run batch-renderer docs/SAMPLE-CONCEPTS.md --dry-run
   

4. Render images:

   pipenv run batch-renderer docs/SAMPLE-CONCEPTS.md
   

Markdown Format

Basic Format

## 1. Section Title

### Concept 1.1: Image Title
A detailed description of the image you want to generate...

### Concept 1.2: Another Image
Another prompt description...

With Metadata

Add metadata as bullet points after the heading to override settings:

### Concept 1.1: Custom Image
- model: GPT-Image-1
- aspect: 16:9
- quality: high
- retries: 5

A detailed prompt for the image...

Standard Metadata Keys

• model - Override the model for this prompt (e.g., GPT-Image-1, Nano-Banana)
• format - Override output format (e.g., png, jpg)
• skip - Set to true to skip this prompt
• retries - Number of retry attempts (default: 3)

Custom Metadata Keys

Any other keys are passed directly to the API via extra_body:

• aspect - Aspect ratio (1:1, 3:2, 2:3, 16:9, auto)
• quality - Image quality (low, medium, high)
• thinking_level - For thinking models (low, medium, high)
• thinking_budget - Thinking budget (extended)
• web_search - Enable web search (true / false)

CLI Usage

batch-renderer [OPTIONS] INPUT_FILE

Options

Option	Description	Default
--model, -m	Model to use	Nano-Banana (or POE_DEFAULT_MODEL env)
--output, -o	Output directory	out
--pattern, -p	Extraction pattern (concept, numbered, simple)	concept
--format, -f	Output image format	png
--flatten	Flatten output (no subdirectories)	false
--dry-run	Extract and display without rendering	false
--no-confirm	Skip confirmation prompt	false
--cache-images	Cache images in logs/image_cache	false
--validation-mode	Metadata validation (strict, lenient, hybrid)	hybrid
--api-key	Poe API key (or POE_API_KEY env)	-

Examples

Basic usage:

batch-renderer prompts.md

Use a specific model:

batch-renderer prompts.md --model GPT-Image-1

Flat output structure:

batch-renderer prompts.md --flatten

Dry run to preview:

batch-renderer prompts.md --dry-run

Batch render without confirmation:

batch-renderer prompts.md --no-confirm

Strict metadata validation:

batch-renderer prompts.md --validation-mode strict

Output Structure

Nested (default)

out/
  1-artificial-lovers/
    concept-1-1-blade-runner-noir-romance.png
    concept-1-2-holographic-love.png
  2-fantastic-eight/
    concept-2-1-renaissance-group-portrait.png

Flattened (with --flatten)

out/
  concept-1-1-blade-runner-noir-romance.png
  concept-1-2-holographic-love.png
  concept-2-1-renaissance-group-portrait.png

Configuration Precedence

Settings are applied in this order (later overrides earlier):

1. Hard-coded defaults (Nano-Banana, png, etc.)
2. Environment variables (POE_DEFAULT_MODEL, POE_API_KEY)
3. Inline metadata (in markdown file)
4. CLI arguments (--model, --format, etc.)

Validation Modes

hybrid (default)

• Standard keys (model, format, skip, retries): Warns on malformed values
• Custom keys: Pass through without validation

strict

• Standard keys: Fails on malformed values
• Custom keys: Pass through without validation

lenient

• All keys: Warns only, never fails

Error Handling

• Automatic retries: Failed requests are retried 3 times by default (configurable per-prompt)
• Text responses: If model returns text instead of image, saves to .txt file with warning
• Partial failures: Continues rendering remaining prompts if one fails
• Summary report: Shows successful, text responses, and failed renders

Pattern Types

concept (default)

Extracts ### Concept X.Y: Title style prompts with section headers.

numbered

Extracts ### X.Y Title style prompts (no "Concept" keyword).

simple

Extracts all level-3 headings as prompts.

Environment Variables

Create a .env file in the project root:

# Required
POE_API_KEY=your_api_key_here

# Optional
POE_DEFAULT_MODEL=Nano-Banana

Development

Project Structure

batch-renderer/
├── src/batch_renderer/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py           # CLI interface
│   ├── config.py        # Configuration management
│   ├── patterns.py      # Prompt extraction patterns
│   └── renderer.py      # Image rendering
├── docs/
│   ├── adr/            # Architecture Decision Records
│   └── SAMPLE-CONCEPTS.md
├── setup.py
├── Pipfile
└── README.md

Running Tests

# Dry run with test file
pipenv run batch-renderer test_prompts.md --dry-run

# Dry run with full sample
pipenv run batch-renderer docs/SAMPLE-CONCEPTS.md --dry-run

Architecture Decisions

See docs/adr/ for detailed design decisions:

• ADR-0001: Core Architecture
• ADR-0002: Prompt Metadata Format

Troubleshooting

"POE_API_KEY not found"

Make sure you've created a .env file with your API key, or pass it via --api-key.

"No prompts found in file"

Check that your markdown file uses the correct pattern format. Use --dry-run to debug extraction.

Model returns text instead of image

This can happen if:

• The model doesn't support image generation
• The model name is incorrect
• The prompt is ambiguous

The tool will save the text response to a .txt file for inspection.

License

MIT

Author

Jérémie Lumbroso with Claude Sonnet 4.5 Additional contributions from Claude Opus 4.8 and Claude Fable 5