image-generation

name image-generation description Generate or edit raster images (photos, illustrations, textures, sprites, mockups, logos, infographics) using the workspace's configured image-generation provider via `onyx-cli image`. Use when the task should produce a brand-new bitmap image, transform an existing image, or derive variants from references — not when the output is better as code-native SVG/vector or built directly in HTML/CSS/canvas. If no image provider is configured, tell the user to set one up at /admin/configuration/image-generation. Image Generation Skill Generate or edit images for the current project (website assets, game assets, UI and product mockups, wireframes, logos, photorealistic images, infographics) using onyx-cli image . Generation runs server-side with whatever provider the admin configured at /admin/configuration/image-generation (OpenAI, Gemini, or Azure) — no API key is needed here. When a provider isn't configured If onyx-cli image … exits with "no image generation provider is configured", stop and tell the user: image generation is unavailable until an admin configures a provider at /admin/configuration/image-generation . Do not try to work around it with another tool. When to use Generate a new image (concept art, product shot, hero, texture, sprite). Generate a new image guided by reference images (style, composition, mood). Edit an existing image (background replacement, object removal, lighting/weather change, compositing, inpainting). Produce many assets or variants for one task. When not to use Extending or matching an existing SVG/vector icon set, logo system, or illustration library already in the repo — edit those directly. Simple shapes, diagrams, wireframes, or icons better produced as SVG / HTML/CSS / canvas. A small project-local asset edit when the source already exists in an editable native format. Any task where the user clearly wants deterministic code-native output, not a generated bitmap. Decision tree Intent — new image or edit of an existing image? Modify an existing image while preserving parts of it → image edit . Images supplied only as references for style/composition/mood, or no images → image generate . Execution — one asset or many? One asset → a single command. Many distinct assets → one command per asset (do not use -n for distinct assets; -n produces variants of one prompt). Assume the user wants a new image unless they clearly ask to change an existing one. Usage Generate (text-to-image) onyx-cli image generate \ -p "A minimal hero of a ceramic coffee mug, clean product photography, soft studio lighting, wide composition with negative space, no text, no watermark" \ --shape landscape \ -o assets/hero.png Edit / composite existing image(s) -i/--input-image may be repeated to composite multiple inputs; the first is the primary edit source. onyx-cli image edit \ -i assets/product.png \ -p "Replace only the background with a warm sunset gradient; keep the product and its edges unchanged" \ -o assets/product-sunset.png Reference images are sent inline, and the sandbox egress proxy rejects any request body over ~32 MiB with a "request body is larger than the limit" ( body_too_large ) error. base64 inflates size by ~33%, so keep each -i image roughly under ~20 MB on disk (downscale large source images first). This only affects edit ; plain generate has a tiny request body. Variants of one prompt onyx-cli image generate -p "Abstract colorful album cover art" -n 3 -o art.png -n > 1 requires a model that supports multiple images per request (e.g. gpt-image-* ). Some models (e.g. dall-e-3 ) only support -n 1 and will error otherwise; if -n > 1 fails, retry with -n 1 . The command prints the saved file path(s), one per line (multiples get a _N suffix). Open the output with view_image to inspect it and iterate with a single targeted prompt change. Flags Flag Short Applies to Default Description --prompt -p both — Text prompt / instruction (required). --output -o both output.png Output path; multiples get _N suffixes. --shape — both square square , portrait , or landscape . --quality -q both provider default Render quality (e.g. low / medium / high / auto ). --num -n both 1 Variants of a single prompt. --input-image -i edit — Input image path; repeat to composite. Workflow Decide intent ( generate vs edit ) and execution (single vs repeated commands). Collect inputs up front: prompt(s), exact in-image text (verbatim), constraints/avoid list, and any input images with their roles. Shape the prompt by specificity: if it's already detailed, normalize it; if generic, add tasteful detail only when it materially improves the result. Run onyx-cli image … , saving project-bound assets into the workspace. Don't overwrite an existing asset unless asked — use a sibling version (e.g. hero-v2.png ). view_image the output; inspect subject, style, composition, and text accuracy; iterate with one targeted change. Report the saved path(s) and the final prompt(s). Prompt schema Use these labeled lines as scaffolding; include only the ones that help. Use case: <photorealistic | product-mockup | ui-mockup | infographic | logo | illustration | concept-art | edit:object | edit:background | edit:style | compositing> Asset type: <where the asset will be used> Primary request: <main prompt> Subject: <main subject> Style/medium: <photo / illustration / 3D / etc.> Composition/framing: <wide / close / top-down; placement> Lighting/mood: <lighting + mood> Color palette: <palette notes> Text (verbatim): "<exact text>" Constraints: <must keep / must avoid> Prompting best practices Structure as scene/backdrop → subject → details → constraints. State the intended use (ad, UI mock, infographic) to set polish level. Use camera/composition language for photorealism. Quote exact in-image text verbatim and specify typography + placement; for tricky words, spell them out and require verbatim rendering. For edits, repeat the invariants every iteration ( change only X; keep Y unchanged ). For multi-image inputs, reference each image and describe how to use it. Iterate with single-change follow-ups. If the prompt is generic, add only detail that materially helps; if it is already detailed, normalize rather than expand.