Menu
Generate and edit images. Outputs PNG files. Use when the user wants any visual creative output, an image generated from a description, or wants to modify an existing image in any way — editing, transforming, or adding visual elements.
| name | imagine |
| description | Generate and edit images. Outputs PNG files. Use when the user wants any visual creative output, an image generated from a description, or wants to modify an existing image in any way — editing, transforming, or adding visual elements. |
zdx imagineGenerate images from text prompts or edit existing images using Gemini or OpenAI image models. Supports text-to-image generation, image editing (inpainting, outpainting, style transfer), and multi-image composition.
zdx imagine --prompt <PROMPT> [OPTIONS]
Options:
-p, --prompt <PROMPT> Text prompt (required)
-s, --source <IMAGE> Source image for editing (repeatable for multi-image)
-o, --out <PATH> Output path (default: $ZDX_HOME/artifacts/image-<timestamp>.png)
--model <MODEL> Model override (default: gemini:gemini-3.1-flash-image-preview)
--aspect <RATIO> Aspect ratio (Gemini only; see table below)
--size <SIZE> 512px | 1K (default) | 2K | 4K
Output: prints the saved file path(s) to stdout.
When running inside zdx (TUI, bot, or CLI), $ZDX_ARTIFACT_DIR is the preferred output location. Pass it via --out:
zdx imagine -p "..." --out "$ZDX_ARTIFACT_DIR/descriptive-name.png"
If no --out is given, images default to $ZDX_HOME/artifacts/.
--model, zdx imagine uses gemini:gemini-3.1-flash-image-preview.zdx imagine also supports both openai:gpt-image-2 and openai-codex:gpt-image-2.openai-codex:gpt-image-2 unless the user explicitly asks for plain openai:gpt-image-2.--aspect currently works with Gemini, but OpenAI/OpenAI Codex require --size instead.1K, 2K, and 4K. 512px is Gemini-only.openai-codex:gpt-image-2 as the preferred OpenAI model path.openai:gpt-image-2 only when the user explicitly asks for the non-Codex OpenAI provider.Preferred OpenAI Codex usage:
zdx imagine -p "A cinematic photo of a red fox in falling snow" --model openai-codex:gpt-image-2 --size 1K
Plain OpenAI usage:
zdx imagine -p "A cinematic photo of a red fox in falling snow" --model openai:gpt-image-2 --size 1K
OpenAI editing:
zdx imagine -p "Add a neon sign above the doorway, keep the rest unchanged" -s street.png --model openai-codex:gpt-image-2 --size 2K
| Mode | Usage | Description |
|---|---|---|
| Text → Image | -p "prompt" | Generate from scratch |
| Edit single image | -p "prompt" -s image.png | Inpaint, outpaint, style transfer, modify |
| Multi-image compose | -p "prompt" -s a.png -s b.png | Combine images into new scene |
Images are saved to $ZDX_ARTIFACT_DIR when set, otherwise $ZDX_HOME/artifacts/. Use --out to specify the path:
zdx imagine -p "..." --out "$ZDX_ARTIFACT_DIR/descriptive-name.png"
Describe the scene, don't just list keywords. A narrative, descriptive paragraph will almost always produce a better, more coherent image than a list of disconnected words.
Create a [style] infographic that explains [concept/topic]. Show [key elements]
with clear labels and [visual metaphor or analogy]. The layout should be
[layout description]. Use [color palette] and [typography style].
[Aspect ratio].
A [style] diagram showing how [process/system] works, step by step.
Label each stage clearly: [stage 1], [stage 2], [stage 3].
Use [visual style: arrows, flow, numbered panels]. [Color scheme].
[Aspect ratio].
A [style] side-by-side comparison of [thing A] vs [thing B].
Each side shows [key differences] with clear labels.
Use [visual contrast: split layout, color coding]. [Aspect ratio].
A [style] annotated breakdown of [subject], with labeled parts showing
[components/layers]. [Drawing style: technical, Da Vinci sketch, blueprint,
cutaway, cross-section]. Notes in English. [Aspect ratio].
A [style] visual timeline of [topic], from [start] to [end].
Key milestones labeled with dates and brief descriptions.
[Layout: horizontal, vertical, spiral]. [Color palette]. [Aspect ratio].
A [style] visual that explains [abstract concept] using the analogy of
[concrete thing]. Show how [mapping between concept and analogy].
Clear labels connecting the analogy to the real concept. [Aspect ratio].
How something works:
zdx imagine -p "A colorful, educational infographic explaining how a CPU executes an instruction. Show the fetch-decode-execute cycle as a circular flow diagram with labeled stages. Each stage has a small illustration: memory fetching data, decoder breaking it down, ALU computing. Flat vector style, vibrant colors on dark background." --aspect 16:9
Concept analogy:
zdx imagine -p "A whimsical illustrated infographic explaining the human immune system as a medieval castle defense. White blood cells as knights, antibodies as archers on walls, the skin as castle walls, fever as pouring boiling oil. Labeled annotations connecting each metaphor to the real biology. Colorful storybook illustration style." --aspect 16:9
Anatomy / breakdown:
zdx imagine -p "Da Vinci style anatomical sketch of a dissected Monarch butterfly. Detailed drawings of the head, wings, and legs on textured parchment with handwritten notes in English explaining each part." --aspect 1:1
Comparison:
zdx imagine -p "A clean, modern split-screen comparison of REST vs GraphQL APIs. Left side shows REST with multiple endpoint arrows, right side shows GraphQL with a single endpoint and flexible query. Color-coded: blue for REST, purple for GraphQL. Flat design, bold labels, white background." --aspect 16:9
Process / step-by-step:
zdx imagine -p "A vibrant infographic explaining photosynthesis as a recipe from a colorful kids' cookbook. Show the 'ingredients' (sunlight, water, CO2) going into a plant 'kitchen' and the 'finished dish' (sugar/energy) coming out. Numbered steps, playful illustrations, bright colors. Suitable for a 4th grader." --aspect 16:9
Timeline:
zdx imagine -p "An illustrated horizontal timeline of the history of programming languages, from Fortran (1957) to Rust (2015). Each milestone shows the language name, year, and a small icon representing its key innovation. Retro-futuristic style with muted earth tones and clean typography." --aspect 21:9
Mental model:
zdx imagine -p "A visual explanation of Git branching using a subway map analogy. The main branch is the main line, feature branches are branch lines that split off and merge back. Commits are stations. Labeled with Git terms (main, feature, merge, rebase). Clean, colorful transit map style." --aspect 16:9
| Ratio | Use case |
|---|---|
1:1 | Icons, logos, social media posts |
3:4 / 4:3 | Portraits / Classic photography |
2:3 / 3:2 | Print photography |
9:16 / 16:9 | Stories, vertical / Banners, widescreen, infographics |
21:9 | Cinematic ultrawide, timelines |
4:5 / 5:4 | Instagram portrait / landscape |
1:4 / 4:1 | Ultra-tall / Ultra-wide strips |
1:8 / 8:1 | Extreme panoramic strips |
Resolution: Default is 1K. Use --size only when you need higher resolution.
Use --source / -s to provide one or more input images for editing. The prompt describes what to change.
Inpainting (add/modify elements):
zdx imagine -p "Add a small knitted wizard hat on the cat's head" -s cat.png
Inpainting (remove elements):
zdx imagine -p "Remove the person from the background, fill with natural scenery" -s photo.png
Style transfer:
zdx imagine -p "Transform this photograph into Van Gogh's Starry Night style. Preserve the composition but render with swirling impasto brushstrokes and deep blues and bright yellows." -s city.jpg
Outpainting / aspect change:
zdx imagine -p "Recreate this image as a cinematic ultrawide banner, extending the background naturally" -s hero.png --aspect 21:9
Color/mood adjustment:
zdx imagine -p "Make this scene a warm golden hour sunset, keeping all subjects the same" -s photo.jpg
Provide multiple --source flags to combine images into a new scene:
Group composition:
zdx imagine -p "An office group photo of these people, making funny faces" \
-s person1.png -s person2.png -s person3.png --aspect 5:4
Product mockup:
zdx imagine -p "Create a professional e-commerce fashion photo of this model wearing this dress" \
-s model.jpg -s dress.jpg
Composite with reference:
zdx imagine -p "Place this logo in the bottom-right corner of this banner image" \
-s banner.png -s logo.png
For non-explainer use cases, see references/prompt-templates.md for templates and examples covering:
$ZDX_ARTIFACT_DIR when set. Use --out for descriptive filenames.--size 2K or 4K only when you specifically need higher resolution.--source with a direct edit instruction — don't describe the whole image.Add, update, or remove models and providers in the zdx LLM registry. Use when the user asks to add a new model, add a new provider, update model pricing or context limits, regenerate default models/config, or says things like "add support for X model", "add the new Y provider", "update pricing for Z", "regenerate models", or "run models update".
Explore options and pick a direction before committing to a goal or plan. Use when the user wants to think through approaches, weigh trade-offs, or decide between alternatives — not yet ready to define success criteria or slice work. Hard rule: no code, files, or implementation until the user explicitly approves a direction.
Shape a fuzzy intention into a concrete, measurable goal with explicit success evidence before starting work. Use when the user asks to define a goal, clarify success criteria, sharpen an objective, or turn "make X better" into something verifiable. Useful as a quick pre-step before planning, debugging, performance work, research, or operations work.
Create a ship-first (ship-shaped) implementation plan with demoable MVP slices. Use when a user asks for an implementation plan, MVP plan, shipping plan, or wants to break down a feature into incremental, demoable slices. Emphasizes user journey order and daily-usable increments over polished completeness.
Use for memory-related tasks: saved notes, factual questions that may already be documented, and saving durable information. Prefer Memory_Search and Memory_Get for discovery; use this skill for routing, note-saving, and filing conventions.
Create, edit, validate, and test ZDX automations stored in `$ZDX_HOME/automations/*.md`. Use when users ask to add or modify automation files, recurring jobs, scheduled prompts, or YAML-frontmatter automation definitions.