Transformation Builder Skill
Understand how the tool works, write a precise query, order multi-step chains correctly, then call transformation_builder.
How this tool actually works (read this first)
transformation_builder is not a capability picker. Its only inputs are:
transformation_builder(query, src?, previous_errors?)
query— a natural-language description of the desired transformation.src— optional ImageKit-hosted source URL (defaults to a sample image).previous_errors— pass the error text from a prior failed call so the tool can self-correct.
Internally the tool: (1) searches ImageKit docs using your query, (2) an LLM turns it into a validated list of transformation steps, (3) the SDK builds the final URL. There is no capability argument — the parameter names below are vocabulary to put into your query, not API fields you set directly. Because step 1 is a doc search over your query text, using the correct ImageKit parameter names and values in the query materially improves the result. Using wrong/invented names sends the search off course.
So your job is: translate the user's vague request into a precise query that references real parameters and values from the reference section below.
When to use (triggers this skill)
- Resize, crop, or focus on a region
- Filters, effects, overlays (image/text/video), watermarks
- Multi-step transformation chains
- Background removal, replacement, or generative fill
- Any AI-powered image editing (change objects/colors/styles, upscale, retouch, drop shadow, variations)
Calling transformation_builder
query: the precise, rewritten description (see Query Crafting). Never pass the user's vague words through unchanged.src: the ImageKit delivery URL to transform, if the user gave one. Must be ImageKit-hosted.- Frame a multi-step request as one query describing the steps in order:
- User: "1) Resize to 800x600 2) Crop to the face"
- Query: "Resize to width 800 and height 600, then crop with focus on the face"
Query Crafting
Rule: rewrite the vague request into a description that names real parameters and values. Use exact parameter names/values when you know them; fall back to plain English only when unsure.
| User says | Weak query | Good query |
|---|---|---|
| "Make the red balls green" | "make red balls green" | "Apply an AI edit (ai_edit) with prompt: change the red balls to green" |
| "Clean it up and put it on white" | "clean up, white background" | "Apply ai_retouch, then ai_remove_background with white background color" |
| "Make it look like a painting" | "painting style" | "Apply ai_edit with prompt: oil-painting style with visible brush strokes" |
| "Crop around the face" | "crop face" | "Resize with focus=face to crop around the detected face" |
| "Text 'Hello' at the bottom" | "add hello text" | "Add a text overlay with text 'Hello', positioned at the bottom (focus=bottom)" |
| "Fit a mobile banner" | "mobile banner" | "Resize to width=640 with aspect_ratio=2-1" |
| "300px wide with a red border" | "resize and border" | "Resize to width=300, then add a border of width 5 and color red" |
| "Higher resolution, it's blurry" | "fix quality" | "Apply ai_upscale, then ai_retouch" |
| "Remove bg and add a shadow" | "remove bg shadow" | "Apply ai_remove_background, then ai_drop_shadow" |
| "Make it wider without stretching" | "make wider" | "Extend the canvas horizontally using a padded crop (crop_mode=pad_extract) with background=genfill so AI fills the new area" |
Intent → real parameter/vocabulary
Use this to translate intent into the correct terms to put in the query. These are the actual parameter names the tool validates against.
| User intent | Use this vocabulary | Notes |
|---|---|---|
| Modify specific objects/regions ("enlarge the cat", "add sunglasses", "make it a painting") | ai_edit (prompt-based) | AI content edit driven by a text prompt |
| Replace the whole background scene ("put them on a beach") | ai_change_background (prompt-based) | Keeps the subject, generates a new scene. Not for plain removal or color changes |
| Remove background → transparent | ai_remove_background | ImageKit-native. For the external remove.bg engine use ai_remove_background_external |
| Extend/outpaint the canvas ("add more sky", "make it panoramic") | padded crop + background=genfill | Generative fill lives in the background param, not a standalone AI field. Takes no prompt |
| Increase resolution / fix low-res | ai_upscale | Boolean; no params |
| Clean up / remove blemishes | ai_retouch | Boolean; no params |
| Realistic shadow under a cut-out subject | ai_drop_shadow | Transparent images only. Optional azimuth, elevation, strength |
| Different version / remix | ai_variation | Boolean; preserves structure |
| Resize / aspect ratio / crop | width, height, aspect_ratio, crop, crop_mode | See Resize & Crop table |
| Smart crop to face/object | focus (auto, face, or an object name) + optional zoom | Object names are COCO classes (person, car, dog, …) |
| Swap one color across all pixels ("all red → blue") | color_replace | Global pixel color swap with tolerance |
| Filters/adjustments (B&W, blur, sharpen, rotate, border, round corners) | grayscale, blur, sharpen, rotation, border, radius, … | See Effects table |
| Overlay a logo/watermark image | text/image overlay | Single overlay concept, typed (see Overlays) |
| Write text on the image | text overlay with text | See Overlays |
There is no "generate an image from scratch" step in this tool — it always transforms an existing
src. To generate images from scratch, use text-to-image generation in the ImageKit DAM (Digital Asset Manager), which is a separate feature fromtransformation_builder.
Key distinction: ai_edit vs color_replace vs ai_change_background
- Changing specific objects/regions ("make the balls bigger", "turn the car red") →
ai_edit - Swapping one color globally across all pixels ("replace all red with blue") →
color_replace - Replacing the entire background scene ("put them on a beach") →
ai_change_background
Ordering multi-step chains
When a request spans multiple operations, chain them in one query in this order:
- Upscale / retouch (quality first)
- AI content edits (
ai_edit) - Background removal / replacement (
ai_remove_background,ai_change_background) - Resize / crop (final dimensions)
- Effects / overlays (finishing touches)
Critical: background removal goes AFTER upscale/retouch, never before.
Correct: ai_upscale → ai_remove_background. Wrong: ai_remove_background → ai_upscale.
Example — "clean up this photo, remove the background, make it 500x500":
→ Query: "Apply ai_retouch, then ai_remove_background, then resize to width=500 and height=500".
Background removal: clarify intent
- If the user says "remove background" ambiguously, ask whether they want:
- Real-time URL —
ai_remove_backgroundin a delivery URL (nothing stored). - Remove and save — apply the background-removal extension and upload the result as a new file version (a media-library operation, not this tool).
- Real-time URL —
- Only use
ai_change_backgroundwhen they want a new background scene. For a plain transparent cut-out or a solid color, useai_remove_background(optionally followed bybackground=a color).
Handling failures
- 400 / Bad Request or validation error: refine the query and retry, passing the error text as
previous_errors. Invoke thesearch-docsskill and callsearch_docsto confirm supported parameters/limits. - 3+ failures: use
search-docsto find supported methods and constraints before retrying. - Unsupported: confirm via docs and offer the closest supported alternative.
Gotchas
- Source URL must be ImageKit-hosted.
- Background removal order matters (upscale/retouch first).
- Generative fill =
background=genfillon a padded/enlarged canvas; it takes no prompt.ai_change_backgroundis the prompt-driven one. ai_drop_shadowneeds a transparent subject (runai_remove_backgroundfirst).- Negative offsets/rotation are written with an
Nprefix in the final URL (the tool handles this) — just describe the value normally.
Parameter reference
These are the real names/values the tool validates. Put them into your query.
Resize & crop
| Parameter | What it does |
|---|---|
width | Output width. Integer px, decimal 0–1 (fraction of original), or an arithmetic expression. |
height | Output height. Same formats as width. |
aspect_ratio | Aspect ratio (e.g. 16-9). Use with width or height; ignored if both are set. |
crop | Resize strategy: force, at_max, at_max_enlarge, at_least, maintain_ratio, maintain_ratio_no_enlarge. |
crop_mode | Pad/extract behavior: pad_resize, extract, pad_extract, pad_resize_no_enlarge, pad_extract_no_shrink. |
focus | Focal point: auto, face, custom, a directional position (center, top, left, bottom_right, …), or an object name (COCO class such as person, car, dog). |
zoom | Zoom factor around the focused area (with face/object focus). |
x, y, x_center, y_center | Region coordinates for extract crops (top-left vs center-based). |
dpr | Device pixel ratio (number or auto) for high-density displays. |
background | Fill for padded areas — see Background modes. |
Background modes (background)
| Value | Meaning |
|---|---|
| a color | Hex (FFFFFF) or CSS name (white, red, …). |
blurred | Blurred version of the image (optionally blurred_<intensity>_<brightness>). |
dominant | The image's dominant color. |
genfill | AI generative fill of the padded area (outpainting). No prompt. |
gradient | Gradient from dominant colors (gradient_dominant, optional palette size 2 or 4). |
AI transforms
| Parameter | What it does |
|---|---|
ai_remove_background | ImageKit-native background removal → transparent. |
ai_remove_background_external | Background removal via external provider (remove.bg). |
ai_edit | Prompt-based AI edit of image content. |
ai_change_background | Prompt-based replacement of the background scene (subject preserved). |
ai_drop_shadow | AI drop shadow (transparent images only). Optional azimuth (0–360), elevation (0–90), strength (0–100). |
ai_upscale | AI super-resolution upscaling. No params. |
ai_retouch | AI quality enhancement / blemish removal. No params. |
ai_variation | Generate a structural variation of the image. No params. |
Effects & enhancement
| Parameter | What it does |
|---|---|
blur | Gaussian blur, 0–100. |
sharpen | Sharpen, 0–100. |
unsharp_mask | Advanced sharpening (radius, sigma, amount, threshold). |
grayscale | Convert to grayscale. |
contrast_stretch | Auto-enhance contrast. |
shadow | Drop shadow under non-transparent pixels (needs transparency). Optional blur, saturation, x_offset, y_offset. |
gradient | Linear gradient overlay (linear_direction, from_color, to_color, stop_point). |
color_replace | Replace a color and similar shades: to_color, tolerance (0–100), optional from_color. |
colorize | Tint the image: color, intensity (0–100). |
border | Border of border_width and color. |
trim | Trim solid edges around the subject. |
rotation | Rotate by degrees (or auto from EXIF). Negative = counter-clockwise. |
flip | h, v, h_v, or v_h. |
radius | Round corners (integer, max for a circle, or per-corner 20_40_80_160). |
opacity | Layer opacity, 0–100. |
distort | Perspective warp (4 coordinate pairs) or arc distortion (degrees). |
Overlays (overlay)
One overlay concept with a typed shape. Each overlay supports position (x, y, x_center, y_center, focus, anchor_point), timing for video (start, end, duration), layer_mode (multiply, cutter, cutout, displace), and a nested transformation list.
| Overlay type | Key fields |
|---|---|
| Text | text, plus styling: font_size, font_family, font_color, inner_alignment, padding, alpha (1–9), typography, line_height, radius, rotation, flip, background. |
| Image | input (media-library path of the overlay image); nested transformations allowed. |
| Video | input (video path); nested transformations + timing. |
| Subtitle | input (subtitle file); styling: font_size, font_family, color, typography, font_outline, font_shadow, background. |
| Solid color | color, plus width, height, radius, alpha, background, gradient. |
Video transforms
| Parameter | What it does |
|---|---|
start_offset, end_offset, duration | Trim the clip (seconds or arithmetic expressions). |
audio_codec | aac, opus, or none (to mute/strip). |
video_codec | h264, vp9, av1, or none. |
streaming_resolutions | Adaptive-bitrate ladder, e.g. [360, 720, 1080]. |
rotation, radius, border, flip | Same as image effects, applied to the video frame. |
Output & delivery
| Parameter | What it does |
|---|---|
format | auto, webp, avif, jpg, png, gif, mp4, webm, orig, … |
quality | 0–100. |
progressive | Progressive JPEG. |
lossless | Lossless WebP/PNG. |
named | Apply a saved named transformation. |
default_image | Fallback image if the source is missing. |
Conditionals
Transformations can be conditional on image properties (e.g. width/height/aspect ratio) — describe the condition in plain language ("if width > 1000, then …") and the tool builds the if/if-else/if-end chain.