transformation-builder

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: transformation-builder
description: "Guidance for building ImageKit image/video transformation URLs with the transformation_builder tool — how the tool works, how to write a good query, how to order multi-step chains, and a reference of every supported parameter. Use before calling transformation_builder. Covers resize/crop/focus, AI edits (change objects, colors, styles), background removal/replacement, generative fill, upscaling, retouching, drop shadows, variations, effects (blur/sharpen/rotate/border/color-replace/gradient), image/text/video overlays, and video transforms."
---

# 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_back