transformation-builder

Transformation Builder スキル

ツールの仕組みを理解し、正確なクエリを記述して、複数ステップのチェーンを正しい順序に並べてから、transformation_builder を呼び出します。

このツールの実際の仕組み（最初にお読みください）

transformation_builder は機能を選択するツールではありません。入力は次のものだけです。

transformation_builder(query, src?, previous_errors?)

• query — 実行したい変換を説明する自然言語の記述です。
• src — ImageKit がホストするソース URL（省略するとサンプル画像が使われます）。
• previous_errors — 以前の呼び出しに失敗した場合、そのエラーテキストを渡すとツールが自動修正を試みます。

内部では、ツールが次の処理を行います。（1）query を使って ImageKit のドキュメントを検索し、（2）LLM が検証済みの変換ステップ一覧に変換し、（3）SDK が最終 URL を生成します。capability 引数はありません。以下のパラメーター名は、query に含める用語であり、直接設定する API フィールドではありません。ステップ 1 では query のテキストを使ってドキュメントを検索するため、正しい ImageKit のパラメーター名と値を query に使うと、結果の精度が大幅に向上します。誤った名前や、実在しない名前を使うと、検索が正しい方向から外れてしまいます。

そのため、あなたの役割は、ユーザーの曖昧なリクエストを、以下のリファレンスセクションにある実在するパラメーター名と値を含む正確なクエリに変換することです。

使用する場面（このスキルが起動する条件）

• リサイズ、切り抜き、または特定の領域へのフォーカス
• フィルター、エフェクト、オーバーレイ（画像／テキスト／動画）、ウォーターマーク
• 複数ステップの変換チェーン
• 背景の削除、置き換え、または生成塗りつぶし
• AI を活用した画像編集（オブジェクト／色／スタイルの変更、アップスケール、レタッチ、ドロップシャドウ、バリエーション）

transformation_builder の呼び出し

• query：正確に書き直した説明です（「クエリの作成」を参照）。ユーザーの曖昧な表現を、そのまま渡してはいけません。
• src：ユーザーが指定した場合は、変換する ImageKit 配信 URL を指定します。ImageKit がホストする URL でなければなりません。
• 複数ステップのリクエストは、順序に沿ってステップを説明する1 つのクエリにまとめます。
  • ユーザー：「1）800x600 にリサイズ　2）顔に合わせて切り抜く」
  • クエリ：「幅を 800、高さを 600 にリサイズしてから、顔にフォーカスして切り抜く」

クエリの作成

ルール：曖昧なリクエストを、実在するパラメーター名と値を含む説明に書き換えてください。分かる場合は正確なパラメーター名と値を使い、不確かな場合に限り平易な英語を使ってください。

ユーザーの表現	不十分なクエリ	適切なクエリ
「赤いボールを緑にして」	「赤いボールを緑にする」	「プロンプトに、赤いボールを緑に変えるよう指定して、ai_edit を適用する」
「きれいにして、白い背景にして」	「きれいにして、白い背景」	「ai_retouch を適用し、その後、背景色を白にして ai_remove_background を適用する」
「絵画のように見せて」	「絵画風」	「プロンプトに、筆跡が見える油絵風と指定して、ai_edit を適用する」
「顔の周りを切り抜いて」	「顔を切り抜く」	「focus=face でリサイズし、検出された顔の周りを切り抜く」
「下部にテキスト『Hello』を追加」	「Hello のテキストを追加」	「テキスト『Hello』のオーバーレイを追加し、下部（focus=bottom）に配置する」
「モバイルバナーに合わせて」	「モバイルバナー」	「width=640、aspect_ratio=2-1 でリサイズする」
「幅 300px、赤い枠線付き」	「リサイズして枠線を追加」	「width=300 にリサイズしてから、幅 5、色を赤にした border を追加する」
「ぼやけているので、解像度を上げて」	「画質を修正」	「ai_upscale を適用し、その後 ai_retouch を適用する」
「背景を削除して影を追加」	「背景削除、影」	「ai_remove_background を適用し、その後 ai_drop_shadow を適用する」
「引き伸ばさずに横幅を広げて」	「横幅を広げる」	「crop_mode=pad_extract のパディング付き切り抜きを使ってキャンバスを横方向に拡張し、background=genfill を指定して AI に新しい領域を塗りつぶさせる」

Intent → 実際のパラメーター／用語

意図をクエリに指定する適切な用語へ変換する際に使用します。これらは、ツールが検証する実際のパラメーター名です。

ユーザーの意図	使用する用語	備考
特定のオブジェクト／領域を変更する（「猫を大きくする」「サングラスを追加する」「絵画風にする」）	ai_edit（プロンプトベース）	テキストプロンプトに基づく AI コンテンツ編集
背景全体のシーンを置き換える（「被写体をビーチに配置する」）	ai_change_background（プロンプトベース）	被写体はそのままに、新しいシーンを生成します。単なる背景の削除や色の変更には使用しません
背景を削除して透明にする	ai_remove_background	ImageKit ネイティブ機能です。外部の remove.bg エンジンを使用する場合は、ai_remove_background_external を使用します
キャンバスを拡張／アウトペイントする（「空をもっと追加する」「パノラマにする」）	パディング付きクロップ + background=genfill	生成塗りつぶしは独立した AI フィールドではなく、background パラメーターで指定します。プロンプトは不要です
解像度を上げる／低解像度を修正する	ai_upscale	ブール値。パラメーターはありません
修正する／シミを除去する	ai_retouch	ブール値。パラメーターはありません
切り抜いた被写体の下にリアルな影を追加する	ai_drop_shadow	透明画像のみ対応します。azimuth、elevation、strength は任意です
別バージョン／リミックスを作成する	ai_variation	ブール値。構成を維持します
サイズ変更／アスペクト比／クロップ	width、height、aspect_ratio、crop、crop_mode	「サイズ変更とクロップ」表を参照してください
顔／オブジェクトに合わせてスマートクロップする	focus（auto、face、またはオブジェクト名）+ 任意の zoom	オブジェクト名は COCO クラスです（person、car、dog、…）
すべてのピクセルで特定の色を置換する（「赤をすべて青にする」）	color_replace	tolerance を指定してピクセル全体の色を置換します
フィルター／調整（白黒、ぼかし、シャープ化、回転、枠線、角丸）	grayscale、blur、sharpen、rotation、border、radius、…	「エフェクト」表を参照してください
ロゴ／透かし画像を重ねる	テキスト／画像のオーバーレイ	型指定された単一の overlay 概念です（「オーバーレイ」を参照）
画像にテキストを追加する	text を指定したテキストオーバーレイ	「オーバーレイ」を参照してください

このツールには「画像を一から生成する」手順はありません。常に既存の src を変換します。画像を一から生成するには、ImageKit DAM（デジタルアセットマネージャー）のテキストから画像を生成する機能を使用してください。これは transformation_builder とは別の機能です。

重要な違い：ai_edit と color_replace と ai_change_background

1. 特定のオブジェクト／領域を変更する（「ボールを大きくする」「車を赤くする」）→ ai_edit
2. すべてのピクセルで特定の色を置換する（「赤をすべて青に置き換える」）→ color_replace
3. 背景全体のシーンを置き換える（「被写体をビーチに配置する」）→ ai_change_background

複数ステップの処理を順番に指定する

複数の操作を含むリクエストでは、次の順序で1つのクエリにまとめて指定します。

1. アップスケール／レタッチ（まず画質を向上）
2. AI コンテンツ編集（ai_edit）
3. 背景の削除／置換（ai_remove_background、ai_change_background）
4. サイズ変更／クロップ（最終寸法）
5. エフェクト／オーバーレイ（仕上げ）

重要：背景の削除はアップスケール／レタッチの後に行い、先に行ってはいけません。 正しい順序：ai_upscale → ai_remove_background。誤った順序：ai_remove_background → ai_upscale。

例 — 「この写真をきれいにして、背景を削除し、500x500にする」： → クエリ：「ai_retouch を適用し、次に ai_remove_background を適用してから、width=500、height=500 にサイズ変更する」。

背景の削除：意図を確認する

• ユーザーの「背景を削除する」という指示が曖昧な場合は、次のどちらを希望するのか確認してください。
  1. リアルタイム URL — 配信 URL で ai_remove_background を使用します（何も保存されません）。
  2. 削除して保存 — 背景削除拡張機能を適用し、結果を新しいファイルバージョンとしてアップロードします（このツールではなく、メディアライブラリの操作です）。
• 新しい背景シーンを希望する場合に限り、ai_change_background を使用してください。透明な切り抜きや単色の背景にする場合は、ai_remove_background を使用します（必要に応じて、その後に background=色を指定します）。

エラーへの対処

1. 400 / Bad Request または検証エラー：クエリを調整して再試行し、previous_errors にエラーテキストを渡します。search-docs スキルを呼び出し、search_docs を使用して、サポートされているパラメーターや制限を確認します。
2. 3 回以上失敗した場合：再試行する前に、search-docs を使用してサポートされているメソッドや制約を確認します。
3. 未サポートの場合：ドキュメントで確認し、最も近い代替手段を提示します。

注意事項

• ソース URL は ImageKit がホストするものでなければなりません。
• 背景を削除する順序が重要です（先にアップスケール／レタッチします）。
• 生成塗りつぶしは、余白を追加／拡大したキャンバス上で background=genfill を指定します。プロンプトは不要です。プロンプトで背景を変更するのは ai_change_background です。
• ai_drop_shadow には透明な被写体が必要です（先に ai_remove_background を実行します）。
• 負のオフセット／回転は、最終 URL では N プレフィックスを付けて記述されます（ツールが処理します）。値は通常どおり説明してください。

---

パラメーターリファレンス

以下は、ツールが検証する実際の名前／値です。クエリに指定してください。

リサイズと切り抜き

パラメーター	機能
width	出力幅です。整数の px、0～1 の小数（元画像に対する割合）、または算術式を指定します。
height	出力高さです。width と同じ形式を指定します。
aspect_ratio	アスペクト比（例：16-9）です。width または height と組み合わせて使用します。両方が設定されている場合は無視されます。
crop	リサイズ方法：force、at_max、at_max_enlarge、at_least、maintain_ratio、maintain_ratio_no_enlarge。
crop_mode	余白追加／切り出しの動作：pad_resize、extract、pad_extract、pad_resize_no_enlarge、pad_extract_no_shrink。
focus	焦点：auto、face、custom、方向を示す位置（center、top、left、bottom_right、…）、またはオブジェクト名（person、car、dog などの COCO クラス）。
zoom	焦点領域のズーム倍率（顔／オブジェクトを焦点に指定する場合）。
x、y、x_center、y_center	extract 切り抜きの領域座標（左上基準または中心基準）。
dpr	高密度ディスプレイ向けのデバイスピクセル比（数値または auto）。
background	余白部分の塗りつぶし方法。「背景モード」を参照してください。

背景モード（background）

値	意味
色	16 進数（FFFFFF）または CSS 名（white、red、…）。
blurred	画像をぼかしたもの（オプションで blurred_<intensity>_<brightness>）。
dominant	画像の主要色。
genfill	余白部分を AI で生成して塗りつぶします（アウトペインティング）。プロンプトは不要です。
gradient	主要色から作成するグラデーション（gradient_dominant、オプションでパレットサイズ 2 または 4）。

AI 変換

パラメーター	機能
ai_remove_background	ImageKit ネイティブの背景削除 → 透明化。
ai_remove_background_external	外部プロバイダー（remove.bg）を介した背景削除。
ai_edit	プロンプトに基づく画像コンテンツの AI 編集。
ai_change_background	プロンプトに基づいて背景のシーンを置き換えます（被写体は保持されます）。
ai_drop_shadow	AI のドロップシャドウ（透明画像のみ）。オプションで azimuth（0～360）、elevation（0～90）、strength（0～100）を指定できます。
ai_upscale	AI による超解像アップスケール。パラメーターはありません。
ai_retouch	AI による画質向上／ blemish の除去。パラメーターはありません。
ai_variation	画像の構造的なバリエーションを生成します。パラメーターはありません。

エフェクトと補正

パラメーター	機能
blur	ガウスぼかし、0～100。
sharpen	シャープ化、0～100。
unsharp_mask	高度なシャープ化（radius、sigma、amount、threshold）。
grayscale	グレースケールに変換します。
contrast_stretch	コントラストを自動補正します。
shadow	透明でないピクセルの下にドロップシャドウを追加します（透明度が必要です）。blur、saturation、x_offset、y_offset は任意です。
gradient	線形グラデーションを重ねます（linear_direction、from_color、to_color、stop_point）。
color_replace	色と類似する色合いを置き換えます：to_color、tolerance（0～100）、任意の from_color。
colorize	画像に色合いを付けます：color、intensity（0～100）。
border	border_width と color で枠線を追加します。
trim	被写体の周囲にある単色の縁をトリミングします。
rotation	度数で回転します（または EXIF に基づく auto）。負の値は反時計回りです。
flip	h、v、h_v、または v_h。
radius	角を丸くします（整数、円形にする max、または角ごとの指定 20_40_80_160）。
opacity	レイヤーの不透明度、0～100。
distort	透視変換（4 組の座標）またはアーク変形（度数）。

オーバーレイ（overlay）

型付きシェイプを使用する単一の overlay 概念です。各オーバーレイは、position（x、y、x_center、y_center、focus、anchor_point）、動画用の timing（start、end、duration）、layer_mode（multiply、cutter、cutout、displace）、およびネストされた transformation リストに対応しています。

オーバーレイの種類	主なフィールド
テキスト	text とスタイル設定：font_size、font_family、font_color、inner_alignment、padding、alpha（1～9）、typography、line_height、radius、rotation、flip、background。
画像	input（オーバーレイ画像のメディアライブラリパス）。ネストされた変換にも対応しています。
動画	input（動画パス）。ネストされた変換とタイミングにも対応しています。
字幕	input（字幕ファイル）。スタイル設定：font_size、font_family、color、typography、font_outline、font_shadow、background。
単色	color と、width、height、radius、alpha、background、gradient。

動画変換

パラメーター	機能
start_offset、end_offset、duration	クリップをトリミングします（秒数または算術式）。
audio_codec	aac、opus、または none（ミュート／音声の除去）。
video_codec	h264、vp9、av1、または none。
streaming_resolutions	アダプティブビットレートの解像度設定。例：[360, 720, 1080]。
rotation、radius、border、flip	画像エフェクトと同じ設定を動画フレームに適用します。

出力と配信

パラメーター	機能
format	auto、webp、avif、jpg、png、gif、mp4、webm、orig、…
quality	0～100。
progressive	プログレッシブ JPEG。
lossless	可逆 WebP／PNG。
named	保存済みの名前付き変換を適用します。
default_image	ソースが見つからない場合に使用するフォールバック画像。

条件分岐

画像のプロパティ（幅／高さ／アスペクト比など）に基づいて変換を条件付きで実行できます。条件を自然言語で（「幅が 1000 を超える場合は、…」のように）記述すると、ツールが if／if-else／if-end の連鎖を構築します。