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 from
transformation_builder
.

Key distinction:

ai_edit

color_replace

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:
1. Real-time URL —
```
ai_remove_background
```
  in a delivery URL (nothing stored).
2. Remove and save — apply the background-removal extension and upload the result as a new file version (a media-library operation, not this tool).
Only use
```
ai_change_background
```
when they want a new background scene. For a plain transparent cut-out or a solid color, use
```
ai_remove_background
```
(optionally followed by
```
background
```
=a color).

Handling failures

400 / Bad Request or validation error: refine the query and retry, passing the error text as
```
previous_errors
```
. Invoke the
```
search-docs
```
skill and call
```
search_docs
```
to confirm supported parameters/limits.
3+ failures: use
```
search-docs
```
to 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
```
=
```
genfill
```
on a padded/enlarged canvas; it takes no prompt.
```
ai_change_background
```
is the prompt-driven one.
```
ai_drop_shadow
```
needs a transparent subject (run
```
ai_remove_background
```
first).
Negative offsets/rotation are written with an
```
N
```
prefix 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_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.

transformation-builder

NPX Install

Tags

SKILL.md Content

Transformation Builder Skill

How this tool actually works (read this first)

When to use (triggers this skill)

Calling
`transformation_builder`

Query Crafting

Intent → real parameter/vocabulary

Key distinction:
`ai_edit`
vs
`color_replace`
vs
`ai_change_background`

Ordering multi-step chains

Background removal: clarify intent

Handling failures

Gotchas

Parameter reference

Resize & crop

Background modes (
`background`
)

AI transforms

Effects & enhancement

Overlays (
`overlay`
)

Video transforms

Output & delivery

Conditionals

transformation-builder

NPX Install

Tags

SKILL.md Content

Transformation Builder Skill

How this tool actually works (read this first)

When to use (triggers this skill)

Calling transformation_builder

Query Crafting

Intent → real parameter/vocabulary

Key distinction: ai_edit vs color_replace vs ai_change_background

Ordering multi-step chains

Background removal: clarify intent

Handling failures

Gotchas

Parameter reference

Resize & crop

Background modes (background)

AI transforms

Effects & enhancement

Overlays (overlay)

Video transforms

Output & delivery

Conditionals

Calling
`transformation_builder`

Key distinction:
`ai_edit`
vs
`color_replace`
vs
`ai_change_background`

Background modes (
`background`
)

Overlays (
`overlay`
)