imagine

Imagine – Image Generation & Editing via zdx imagine

Generate images from text prompts or edit existing images using Gemini, OpenAI, or Alibaba (Qwen-Image) image models. Supports text-to-image generation, image editing (inpainting, outpainting, style transfer), and multi-image composition.

CLI reference

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 — written exactly as given (default: $ZDX_HOME/artifacts/image-<timestamp>.<ext>)
      --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 exact saved file path(s) to stdout. --out is honored literally; the model picks the image format (often JPEG for Gemini), so a file named .png may actually hold JPEG bytes. That is fine — zdx reads images by content, not extension. Use --out to control the path and always view/attach the printed path.

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/.

Provider guidance

• Default: If you do not pass --model, zdx imagine uses gemini:gemini-3.1-flash-image-preview.
• OpenAI support: zdx imagine also supports both openai:gpt-image-2 and openai-codex:gpt-image-2.
• Preferred OpenAI path: When using OpenAI, prefer openai-codex:gpt-image-2 unless the user explicitly asks for plain openai:gpt-image-2 or for GPT Image 2.5.
• GPT Image 2.5 (explicit selection, API key): openai:gpt-image-2.5-flare (fast, the default choice for most work) and openai:gpt-image-2.5-sunburst (higher precision for detailed edits, slower). Dated snapshots such as openai:gpt-image-2.5-flare-2026-09-08 also work. Use them only when the user asks for GPT Image 2.5 or the newest OpenAI image model. Requires OPENAI_API_KEY.
• Codex is server-managed: openai-codex:* image requests run on the ChatGPT subscription, and the backend picks the image engine, size, and quality itself. Probes showed it ignores the requested image model, --size, and quality, and it never reports which model ran. openai-codex:gpt-image-2.5-* is accepted but not honored as a selection; zdx imagine prints a warning on stderr. Do not tell the user Codex gave them Image 2 or Image 2.5 specifically. For an explicit variant, use openai:gpt-image-2.5-flare or -sunburst.
• Alibaba (Qwen-Image) support: zdx imagine supports alibaba:qwen-image-3.0-pro, alibaba:qwen-image-3.0, and alibaba:qwen-image-2.0-pro — combined text-to-image + editing models on Alibaba DashScope. Requires ALIBABA_API_KEY. Use them when the user asks for Qwen/Alibaba image generation.
• Preferred Alibaba path: Use alibaba:qwen-image-3.0-pro. It is the strongest of the three at dense layouts, small text (~10px), and multilingual typography. Fall back to alibaba:qwen-image-3.0 for cheaper/faster runs, and to alibaba:qwen-image-2.0-pro only when explicitly asked.
• Gemini vs OpenAI/Alibaba: --aspect currently works with Gemini only; OpenAI, OpenAI Codex, and Alibaba require --size instead.
• OpenAI size support: openai: passes 1K, 2K, or 4K to the image tool (only 1K was checked live). openai-codex: accepts the flag but the backend chooses its own output size (e.g. 1536x1024 for --size 1K). 512px is Gemini-only.
• Alibaba size support: All Alibaba Qwen-Image models support 512px, 1K, and 2K (not 4K).