# Image Tools

> AI image generation and editing. Provides generate_image and edit_image tools for creating and modifying images.

- Skill: `kunlabai/image-tools` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kunlabai/image-tools`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kunlabai/image-tools/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KunLabAI (https://skillmd.com/u/kunlabai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kunlabai/image-tools

---

# Image Tools

Use this skill when the user asks to create, draw, generate, design, edit, modify, or enhance images.

Loading this skill activates the `generate_image` and `edit_image` tools.

**IMPORTANT**: After loading this skill, you MUST call either `generate_image` or `edit_image` tool to perform image operations. Do NOT call `image_tools` directly - it is NOT a tool name.

## Tool: generate_image (text-to-image)

Generate images **from scratch** using only a text prompt. No reference image is used.

### When to Use

- User asks to create a **brand new** image with no reference image.
- User asks to "regenerate" an image with a refined prompt (starting over, not editing).

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Detailed English description of the image. See [Prompt Writing Guide](#prompt-writing-guide) below. |
| `aspect_ratio` | string | No | Image aspect ratio (e.g. "1:1", "16:9", "9:16", "4:3"). Default is "auto". |
| `n` | integer | No | Number of images to generate (1-4). Default is 1. |

### Example

```
generate_image(
  prompt="A serene Japanese garden with cherry blossoms, koi pond, and a wooden bridge, watercolor painting style, soft morning light filtering through branches",
  aspect_ratio="16:9",
  n=1
)
```

The tool returns image URLs in markdown format. Include them in your response.

## Tool: edit_image (image-to-image)

Edit or generate an image **using one or more reference images as the visual basis**. The reference images guide the output — the AI sees them and builds upon them.

### When to Use

- **Reference-based generation**: User provides a reference image and asks to create new content based on it (e.g. "use this character to generate a three-view sheet", "put this person in a fantasy world").
- **Character consistency**: User wants to maintain a character's appearance across different scenes or poses.
- **Style transfer**: Transform an image into a different art style while preserving the content.
- **Inpainting / Partial edit**: Modify a specific region of an image while keeping everything else unchanged (e.g. "change the sofa color", "remove the person in the background").
- **Multi-image composition**: Combine elements from multiple reference images into a new scene (e.g. "put the dress from image 1 on the person in image 2").
- **High-fidelity preservation**: Preserve critical details (face, logo, text) while making other changes.

**Key decision rule**: Whenever a reference image exists (from canvas, chat history, or user upload) and the user wants the output to visually relate to it, use `edit_image`. Only use `generate_image` when creating from pure text with no visual reference.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image_url` | string | No* | Single reference image URL/path (e.g. `/api/media/filename.jpg`). Do NOT pass base64. |
| `image_urls` | string[] | No* | Multiple reference image URLs/paths (up to 5). Use for multi-image composition. |
| `prompt` | string | Yes | Description of the desired output. See [Edit Prompt Patterns](#edit-prompt-patterns) below for templates. |
| `aspect_ratio` | string | No | Output aspect ratio. Single-image edit follows input; multi-image defaults to first image (can be overridden). |
| `quality` | string | No | Output quality ("standard" or "hd"). Default uses global config. |

\* Either `image_url` or `image_urls` must be provided. `image_urls` takes precedence.

### Examples

**Single-image reference** (character in new scene):
```
edit_image(
  image_url="/api/media/character-ref.png",
  prompt="The same woman from the reference image, now standing in an ancient Chinese xianxia world on a floating mountain path, wearing flowing white immortal robes with jade accessories, cinematic golden-hour lighting, volumetric fog, 8k ultra-detailed",
  aspect_ratio="16:9"
)
```

**Multi-image composition** (combine elements):
```
edit_image(
  image_urls=[
    "/api/media/character-sheet-1.png",
    "/api/media/character-sheet-2.png"
  ],
  prompt="An epic battle scene between the two characters from the reference images. Character 1 (from first image) leaping with a light sword overhead strike, Character 2 (from second image) blocking with dual axes, energy collision sparks. Rain-soaked cyberpunk street at night, neon reflections on wet ground, low-angle cinematic shot, 8k",
  aspect_ratio="16:9"
)
```

**Inpainting** (partial edit):
```
edit_image(
  image_url="/api/media/living-room.png",
  prompt="Using the provided image, change only the blue sofa to a vintage brown leather chesterfield sofa. Keep everything else exactly the same, preserving the original lighting, shadows, and composition"
)
```

**Style transfer**:
```
edit_image(
  image_url="/api/media/city-photo.jpg",
  prompt="Transform this photograph into the artistic style of Vincent van Gogh's Starry Night. Preserve the original composition of buildings and streets, but render all elements with swirling impasto brushstrokes and a dramatic palette of deep blues and bright yellows",
  quality="hd"
)
```

The tool returns the edited/generated image URL in markdown format.

## Decision Guide

| Scenario | Tool | Reason |
|----------|------|--------|
| "Draw me a cat" (no reference) | `generate_image` | Pure text-to-image |
| "Put this character in a forest" (has reference) | `edit_image` | Reference image guides character appearance |
| "Generate a three-view sheet based on this image" | `edit_image` | Reference image provides the character to replicate |
| "Change only the background to sunset" (has image) | `edit_image` | Inpainting — partial edit |
| "Regenerate with a better prompt" (starting over) | `generate_image` | Discarding previous result, fresh generation |
| "Make this image anime style" | `edit_image` | Style transfer on existing image |
| "Put dress from image A on person from image B" | `edit_image` + `image_urls` | Multi-image composition |
| "Add this logo to her t-shirt" (2 images) | `edit_image` + `image_urls` | High-fidelity detail merging |
| "Refer to my original two character sheets" | `edit_image` + `image_urls` | Combining elements from multiple sources |

---

## Prompt Writing Guide

**Core principle: Describe the scene narratively, don't just list keywords.**

The model's strength is language understanding. A descriptive paragraph always produces better results than a keyword list.

### Structure Template

Build prompts in this order:

1. **Subject** — Who/what is the main focus?
2. **Action/Pose** — What are they doing?
3. **Setting/Background** — Where is this happening?
4. **Style** — What visual style? (photorealistic, anime, oil painting, pencil sketch, etc.)
5. **Technical details** — Lighting, camera angle, resolution.

**Good prompt:**
> "A weathered old fisherman mending nets on a wooden dock at golden hour, Mediterranean fishing village in the background with whitewashed buildings and blue shutters, oil painting style with visible brushstrokes, warm amber lighting, eye-level composition"

**Bad prompt (keyword soup):**
> "fisherman, dock, sunset, Mediterranean, oil painting, detailed, 8k"

### Style Keywords Reference

| Category | Examples |
|----------|----------|
| Photorealistic | "photograph", "studio-lit product photo", "DSLR shot", "street photography" |
| Illustration | "digital illustration", "concept art", "storybook illustration" |
| Painting | "oil painting", "watercolor", "acrylic on canvas", "impressionist" |
| Anime/Manga | "anime style", "cel-shaded", "manga illustration", "Studio Ghibli style" |
| 3D/CG | "3D render", "Pixar style", "Unreal Engine", "isometric" |
| Sketch | "pencil sketch", "charcoal drawing", "ink wash", "line art" |
| Design | "vector icon", "flat design", "minimalist", "infographic" |

### Aspect Ratio Guide

| Ratio | Best for |
|-------|----------|
| `1:1` | Avatars, icons, social media thumbnails |
| `16:9` / `9:16` | Widescreen scenes, mobile wallpapers, stories |
| `4:3` / `3:4` | Presentations, classic portraits |
| `3:2` / `2:3` | Photography, movie stills |
| `2:1` / `1:2` | Banners, panoramic headers |
| `auto` | Let model choose the best ratio for the prompt |

---

## Edit Prompt Patterns

When using `edit_image`, use these proven prompt patterns for best results:

### Pattern 1: Inpainting (Partial Edit)

Change a specific element while preserving everything else.

**Template:**
> "Using the provided image, change only the [specific element] to [new description]. Keep everything else in the image exactly the same, preserving the original style, lighting, and composition."

**Examples:**
- "Using the provided image, change only the blue car to a red vintage Mustang. Keep the street, buildings, and sky unchanged."
- "Remove the person standing in the background. Fill the area with the surrounding environment naturally."

### Pattern 2: Style Transfer

Recreate the content in a different artistic style.

**Template:**
> "Transform the provided [subject description] into the artistic style of [target style]. Preserve the original composition but render it with [description of stylistic elements]."

**Examples:**
- "Transform this city photograph into a Studio Ghibli anime scene with soft pastel colors and hand-painted textures."
- "Render this portrait as a Renaissance oil painting with dramatic chiaroscuro lighting and rich earth tones."

### Pattern 3: Character in New Scene

Place a character from reference into a completely new environment.

**Template:**
> "The same [character description from reference] from the reference image, now [action/pose] in [new environment]. Preserve the character's [key features to keep]. [Style and technical details]."

**Examples:**
- "The same silver-haired cyberpunk woman from the reference, now fighting in a neon-lit rain-soaked alley. Preserve her chrome dress, blue plasma lines, and cybernetic spine interface. Low-angle cinematic shot, 8k."

### Pattern 4: Multi-Image Composition

Combine elements from multiple reference images.

**Template:**
> "Create a new image by combining elements from the provided images. Take the [element from image 1] and [action] with the [element from image 2]. The final image should be [description of final scene]. Adjust lighting and shadows to create a cohesive result."

**Examples:**
- "Take the blue floral dress from the first image and put it on the woman from the second image. Generate a realistic full-body e-commerce fashion photo with studio lighting."
- "Place the product from image 1 into the kitchen scene from image 2, matching the lighting and perspective naturally."

### Pattern 5: High-Fidelity Preservation

When critical details (face, logo, text) MUST be preserved exactly.

**Template:**
> "Using the provided image(s), [edit description]. Ensure that [critical element] remains completely unchanged. The [modified element] should [integration description]."

**Examples:**
- "Add the logo from the second image onto her black t-shirt. Ensure the woman's face and features remain completely unchanged. The logo should look naturally printed on the fabric, following the folds."
- "Change the background to a tropical beach. The person's face, hair, clothing, and pose must remain pixel-perfect identical."

### Pattern 6: Three-View / Character Sheet

Generate a character reference sheet from a single image.

**Template:**
> "Create a professional character reference sheet showing [character from reference] in three views: front view, right side view, and back view. Neutral standing pose, pure white background, consistent proportions across all views, character design sheet style."

---

## Tips

- **Always write prompts in English** for best quality, even when the user speaks another language.
- For `edit_image`, use the file path from canvas nodes or previous generations — never paste base64 data.
- When multiple images are needed from the same prompt, set `n` parameter on `generate_image` instead of calling multiple times.
- **Multi-image editing**: When the user references multiple images (e.g. "refer to the two character images I sent earlier"), use `image_urls` array. Up to 5 images supported.
- **Single vs multi aspect ratio**: Single-image edit always follows the input image's aspect ratio (cannot be overridden). Multi-image edit defaults to the first image but can be overridden with `aspect_ratio`.
- **Iterative refinement**: Use each edit output as the input for the next edit to progressively refine — describe only the incremental changes needed.
- **Accurate text in images**: To render text in generated images, put the desired text in quotes and describe its placement clearly (e.g. 'the word "HELLO" in bold serif font centered on the banner').