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.

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.

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 vs color_replace vs ai_change_background

1. Changing specific objects/regions ("make the balls bigger", "turn the car red") → ai_edit
2. Swapping one color globally across all pixels ("replace all red with blue") → color_replace
3. 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:

1. Upscale / retouch (quality first)
2. AI content edits (ai_edit)
3. Background removal / replacement (ai_remove_background, ai_change_background)
4. Resize / crop (final dimensions)
5. 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

1. 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.
2. 3+ failures: use search-docs to find supported methods and constraints before retrying.
3. 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

Background modes (background)

AI transforms

Effects & enhancement

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.

Video transforms

Output & delivery

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.