scaryrawr/image-gen

Ollama Image Generation

Generate images locally with a single helper that supports both Ollama CLI and REST backends. This feature is currently macOS-only and uses Ollama's experimental image generation support.

Installed Models

Before generating images, check which models are locally available by calling the Ollama API:

curl -s http://localhost:11434/api/tags | jq -r '.models[].name'

Important: If you see a quantized variant with a suffix (e.g. x/z-image-turbo:q4_K_M), use that exact ID rather than the base name.

Models

Z-Image Turbo (default)

6B parameter model from Alibaba's Tongyi Lab. Best for photorealistic images and bilingual (English/Chinese) text rendering. Apache 2.0 licensed.

FLUX.2 Klein

Black Forest Labs' fast image-generation model (4B and 9B sizes). Best for readable text in images, UI mockups, and typography-heavy designs.

• 4B: Apache 2.0 (commercial use OK)
• 9B: FLUX Non-Commercial License v2.1

Model Selection Guide

| Need | Recommended Model | | ----------------------------------- | ----------------------------------------- | | Photorealistic portraits/scenes | x/z-image-turbo | | Chinese text rendering | x/z-image-turbo | | Readable text in images (signs, UI) | x/flux2-klein | | Commercial use | x/z-image-turbo or x/flux2-klein (4B) | | General purpose | x/z-image-turbo |

Default to x/z-image-turbo unless the user has a specific need for text rendering in images.

Generating Images

Use the helper script (backend defaults to auto, which prefers CLI when available):

./scripts/generate-image.sh --prompt "Young woman in a cozy coffee shop, natural window lighting, wearing a cream knit sweater, holding a ceramic mug, soft bokeh background"

Choose a specific model and image size:

./scripts/generate-image.sh \
  --model x/flux2-klein \
  --size 512x512 \
  --output my-image.png \
  --prompt "A neon sign reading OPEN 24 HOURS in a rainy alley"

Use richer generation controls (CLI backend):

./scripts/generate-image.sh \
  --backend cli \
  --model x/flux2-klein \
  --width 1024 \
  --height 1024 \
  --steps 20 \
  --seed 42 \
  --negative-prompt "blurry, low quality, distorted" \
  --output detailed.png \
  --prompt "UI dashboard mockup with clean typography and clear labels"

Images are saved to the current working directory by default unless --output is provided. Always tell the user where the generated image was saved.

Backend Selection

| Backend | Description | | ------- | ----------- | | auto (default) | Prefers ollama run when available; falls back to REST | | cli | Uses ollama run directly (supports richer options) | | rest | Uses POST /v1/images/generations |

If requested model is missing, the script attempts ollama pull <model>.

Script Options

| Option | Default | Description | | ------ | ------- | ----------- | | --prompt | (required) | The text prompt | | --model | x/z-image-turbo | Ollama model name | | --size | 1024x1024 | Image dimensions (WxH) | | --width / --height | unset | Size aliases (must be used together) | | --output | image_YYYYMMDD_HHMMSS.png | Output file path | | --backend | auto | auto, cli, or rest | | --steps | unset | Denoising steps (CLI backend only) | | --seed | unset | Random seed (CLI backend only) | | --negative-prompt | unset | Negative prompt text (CLI backend only) |

Capability Matrix

| Capability | CLI backend | REST backend | | ---------- | ----------- | ------------ | | Basic prompt + model + size | ✅ | ✅ | | steps / seed / negative prompt | ✅ | ❌ | | width / height aliases | ✅ | ✅ (normalized to size) |

If --backend rest is forced with CLI-only options, the script fails with an actionable error.

Direct curl Example

You can still call the REST API directly:

curl -s http://localhost:11434/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x/z-image-turbo",
    "prompt": "A sunset over the ocean with dramatic clouds",
    "size": "1024x1024",
    "response_format": "b64_json"
  }' | jq -r '.data[0].b64_json' | base64 -d > output.png

Image Size

Control the output dimensions with --size (or --width + --height). Format is WxH. Smaller images generate faster and use less memory.

Common sizes: 512x512, 768x768, 1024x1024

Workflow

1. Check installed models — run curl -s http://localhost:11434/api/tags to list available models. Note any quantized variants (e.g. :q4_K_M) and use the exact ID.
2. Confirm the user's prompt and preferences (model, size, style, optional steps/seed/negative prompt)
3. Pick the starting model based on the request: default to x/z-image-turbo, but prefer x/flux2-klein for text-heavy images, signage, UI, or other typography-sensitive work
4. Run the helper script with --backend auto unless the user explicitly requests a backend (use the exact model ID from step 1, including any quantization suffix)
5. If advanced controls are requested, prefer --backend cli (or rely on auto when CLI is available)
6. Inspect the generated image before surfacing it to the user and compare it against the prompt, with extra attention to text accuracy, composition, subject fidelity, and obvious artifacts
7. If the image misses the prompt, refine the next attempt instead of immediately returning it: tighten the prompt, switch to a more suitable model, adjust size, or add CLI-only controls such as --negative-prompt, --steps, or --seed
8. Repeat the evaluate-and-refine loop for up to 4 total attempts, keeping track of which output best matches the request
9. Return the best image you produced, report the output file location, and note any meaningful limitation only if the best result still falls short of the prompt
10. If the user wants further changes after that, continue iterating with modified prompt, size, model, or advanced controls

Prompting Tips

• Be specific and descriptive: include lighting, composition, style, and mood
• For photorealistic results, mention camera settings (e.g., "shot on 35mm film", "soft bokeh")
• For creative work, reference art styles (e.g., "watercolor", "surreal double exposure")
• Keep prompts focused on a single subject or scene for best results