Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Image Generation

Generate a single image and save it to a file with --image.

Basic Usage

zo --image images/cover.png 'Painterly forest at sunrise'

--image is a dedicated single-shot mode. zo writes the generated image bytes to the target path and prints a simple success line when the file is saved.

How It Works

  • --image is single-shot only. It does not support --chat, --files, or --shell.
  • zo sends a non-streaming OpenRouter chat completion request and uses the first generated image in the response.
  • Output is written inside the current workspace only. Hidden paths stay blocked unless you add --hidden.
  • If the target file already exists, zo asks before overwriting it unless you pass --accept-writes.
  • With --non-interactive, overwrite prompts are suppressed and existing files are left unchanged unless --accept-writes is set.

Prompt Input

Image mode keeps the same prompt entry patterns as normal single-shot mode:

# Plain prompt
zo --image out/poster.png 'Retro travel poster for Berlin'
 
# Slash model override
zo --image out/poster.png /myimage 'Retro travel poster for Berlin'
 
# Prompt text plus piped STDIN
cat brief.txt | zo --image out/mockup.png 'Landing page concept'

A more complex example also using zo to dynamically analyze the current path and then generating an architecture overview. The first instance has read access only, while the second one can only output exactly the requested image:

# analyze repo and create architecture diagram
zo --files read \
  '/flash summarize the core architecture of this project. Be very concise, the output will be used by an AI image model to create an archticture diagram. use short bullet points. focus on the relations of different components.' \
  | zo --image arch.png --accept-writes --model banana \
    'create a software architecture diagram of the described project in C4 style'

Unlike text mode, image mode does not parse file markers. @photo.png, !out.png, and @!draft.png are sent as literal prompt text.

Model Selection

If you do not choose a model explicitly, image mode defaults to:

google/gemini-2.5-flash-image

If you override the model with --model or /alias, zo checks OpenRouter's /models/user discovery response:

  • Image-only models are requested with ["image"]
  • Text+image models are requested with ["image", "text"]
  • Text-only models are rejected before the generation request is sent

Debug Mode

Use --debug to inspect the image request before it is sent:

zo --debug --image out/concept.png 'Brutalist dashboard illustration'

Debug output includes:

  • Selected model
  • Derived output modalities
  • Prompt preview
  • Output path

Common Examples

# Generate an app icon
zo --image assets/icon.png 'Flat blue compass app icon on transparent background'
 
# Generate from a brief file
cat creative-brief.txt | zo --image renders/hero.png
 
# Auto-approve overwrite
zo --image assets/banner.jpg --accept-writes 'Wide product banner with soft studio lighting'

Limitations in v1

  • Text-to-image only
  • One output file per request
  • No terminal image preview
  • No image editing, input images, aspect ratio, or size flags yet