🎨 Data Designer Tutorial: Image-to-Image Editing¶
📚 What you'll learn¶
This notebook shows how to chain image generation columns: first generate animal portraits from text, then edit those generated images by adding accessories and changing styles—all without loading external datasets.
- 🖼️ Text-to-image generation: Generate images from text prompts
- 🔗 Chaining image columns: Use
ImageContextto pass generated images to a follow-up editing column - 🎲 Sampler-driven diversity: Combine sampled accessories and settings for varied edits
This tutorial uses an autoregressive model (one that supports both text-to-image and image-to-image generation via the chat completions API). Diffusion models (DALL·E, Stable Diffusion, etc.) do not support image context—see Tutorial 5 for text-to-image generation with diffusion models.
Prerequisites: This tutorial uses OpenRouter with the Flux 2 Pro model. Set
OPENROUTER_API_KEYin your environment before running.
If this is your first time using Data Designer, we recommend starting with the first notebook in this tutorial series.
📦 Import Data Designer¶
data_designer.configprovides the configuration API.DataDesigneris the main interface for generation.
import base64
from pathlib import Path
from IPython.display import Image as IPImage
from IPython.display import display
import data_designer.config as dd
from data_designer.interface import DataDesigner
⚙️ Initialize the Data Designer interface¶
We initialize Data Designer without arguments here—the image model is configured explicitly in the next cell.
data_designer = DataDesigner()
🎛️ Define an image model¶
We need an autoregressive model that supports both text-to-image and image-to-image generation via the chat completions API. This lets us generate images from text and then pass those images as context for editing.
- Use
ImageInferenceParamsso Data Designer treats this model as an image generator. - Image-specific options are model-dependent; pass them via
extra_body.
Note: This tutorial uses the Flux 2 Pro model via OpenRouter. Set
OPENROUTER_API_KEYin your environment.
MODEL_PROVIDER = "openrouter"
MODEL_ID = "black-forest-labs/flux.2-pro"
MODEL_ALIAS = "image-model"
model_configs = [
dd.ModelConfig(
alias=MODEL_ALIAS,
model=MODEL_ID,
provider=MODEL_PROVIDER,
inference_parameters=dd.ImageInferenceParams(
extra_body={"height": 512, "width": 512},
),
)
]
🏗️ Build the configuration¶
We chain two image generation columns:
- Sampler columns — randomly sample animal types, accessories, settings, and art styles
- First image column — generate an animal portrait from a text prompt
- Second image column with context — edit the generated portrait using
ImageContext
config_builder = dd.DataDesignerConfigBuilder(model_configs=model_configs)
# 1. Sampler columns for diversity
config_builder.add_column(
dd.SamplerColumnConfig(
name="animal",
sampler_type=dd.SamplerType.CATEGORY,
params=dd.CategorySamplerParams(
values=["cat", "dog", "fox", "owl", "rabbit", "panda"],
),
)
)
config_builder.add_column(
dd.SamplerColumnConfig(
name="accessory",
sampler_type=dd.SamplerType.CATEGORY,
params=dd.CategorySamplerParams(
values=[
"a tiny top hat",
"oversized sunglasses",
"a red bow tie",
"a knitted beanie",
"a flower crown",
"a monocle and mustache",
"a pirate hat and eye patch",
"a chef hat",
],
),
)
)
config_builder.add_column(
dd.SamplerColumnConfig(
name="setting",
sampler_type=dd.SamplerType.CATEGORY,
params=dd.CategorySamplerParams(
values=[
"a cozy living room",
"a sunny park",
"a photo studio with soft lighting",
"a red carpet event",
"a holiday card backdrop with snowflakes",
"a tropical beach at sunset",
],
),
)
)
config_builder.add_column(
dd.SamplerColumnConfig(
name="art_style",
sampler_type=dd.SamplerType.CATEGORY,
params=dd.CategorySamplerParams(
values=[
"a photorealistic style",
"a Disney Pixar 3D render",
"a watercolor painting",
"a pop art poster",
],
),
)
)
# 2. Generate animal portrait from text
config_builder.add_column(
dd.ImageColumnConfig(
name="animal_portrait",
prompt="A close-up portrait photograph of a {{ animal }} looking at the camera, studio lighting, high quality.",
model_alias=MODEL_ALIAS,
)
)
# 3. Edit the generated portrait
config_builder.add_column(
dd.ImageColumnConfig(
name="edited_portrait",
prompt=(
"Edit this {{ animal }} portrait photo. "
"Add {{ accessory }} on the animal. "
"Place the {{ animal }} in {{ setting }}. "
"Render the result in {{ art_style }}. "
"Keep the animal's face, expression, and features faithful to the original photo."
),
model_alias=MODEL_ALIAS,
multi_modal_context=[dd.ImageContext(column_name="animal_portrait")],
)
)
data_designer.validate(config_builder)
[03:33:22] [INFO] ✅ Validation passed
🔁 Preview: quick iteration¶
In preview mode, generated images are stored as base64 strings in the dataframe. Use this to iterate on your prompts, accessories, and sampler values before scaling up.
preview = data_designer.preview(config_builder, num_records=2)
[03:33:22] [INFO] 📺 Preview generation in progress
[03:33:22] [INFO] |-- 🔒 Jinja rendering engine: secure
[03:33:22] [INFO] ✅ Validation passed
[03:33:22] [INFO] ⛓️ Sorting column configs into a Directed Acyclic Graph
[03:33:22] [INFO] 🩺 Running health checks for models...
[03:33:22] [INFO] |-- 👀 Checking 'black-forest-labs/flux.2-pro' in provider named 'openrouter' for model alias 'image-model'...
[03:33:33] [INFO] |-- ✅ Passed!
[03:33:33] [INFO] 🎲 Preparing samplers to generate 2 records across 4 columns
[03:33:33] [INFO] 🖼️ image model config for column 'animal_portrait'
[03:33:33] [INFO] |-- model: 'black-forest-labs/flux.2-pro'
[03:33:33] [INFO] |-- model alias: 'image-model'
[03:33:33] [INFO] |-- model provider: 'openrouter'
[03:33:33] [INFO] |-- inference parameters:
[03:33:33] [INFO] | |-- generation_type=image
[03:33:33] [INFO] | |-- max_parallel_requests=4
[03:33:33] [INFO] | |-- extra_body={'height': 512, 'width': 512}
[03:33:33] [INFO] ⚡️ Processing image column 'animal_portrait' with 4 concurrent workers
[03:33:33] [INFO] ⏱️ image column 'animal_portrait' will report progress after each record
[03:33:42] [INFO] |-- ⛅ image column 'animal_portrait' progress: 1/2 (50%) complete, 1 ok, 0 failed, 0.11 rec/s, eta 8.9s
[03:33:44] [INFO] |-- ☀️ image column 'animal_portrait' progress: 2/2 (100%) complete, 2 ok, 0 failed, 0.19 rec/s, eta 0.0s
[03:33:44] [INFO] 🖼️ image model config for column 'edited_portrait'
[03:33:44] [INFO] |-- model: 'black-forest-labs/flux.2-pro'
[03:33:44] [INFO] |-- model alias: 'image-model'
[03:33:44] [INFO] |-- model provider: 'openrouter'
[03:33:44] [INFO] |-- inference parameters:
[03:33:44] [INFO] | |-- generation_type=image
[03:33:44] [INFO] | |-- max_parallel_requests=4
[03:33:44] [INFO] | |-- extra_body={'height': 512, 'width': 512}
[03:33:44] [INFO] ⚡️ Processing image column 'edited_portrait' with 4 concurrent workers
[03:33:44] [INFO] ⏱️ image column 'edited_portrait' will report progress after each record
[03:33:56] [INFO] |-- 😐 image column 'edited_portrait' progress: 1/2 (50%) complete, 1 ok, 0 failed, 0.08 rec/s, eta 12.5s
[03:33:57] [INFO] |-- 🤩 image column 'edited_portrait' progress: 2/2 (100%) complete, 2 ok, 0 failed, 0.15 rec/s, eta 0.0s
[03:33:57] [INFO] 📊 Model usage summary:
[03:33:57] [INFO] |-- model: black-forest-labs/flux.2-pro
[03:33:57] [INFO] |-- tokens: input=3060, output=0, total=3060, tps=126
[03:33:57] [INFO] |-- requests: success=4, failed=0, total=4, rpm=9
[03:33:57] [INFO] |-- images: total=4
[03:33:57] [INFO] 📐 Measuring dataset column statistics:
[03:33:57] [INFO] |-- 🎲 column: 'animal'
[03:33:57] [INFO] |-- 🎲 column: 'accessory'
[03:33:57] [INFO] |-- 🎲 column: 'setting'
[03:33:57] [INFO] |-- 🎲 column: 'art_style'
[03:33:57] [INFO] |-- 🖼️ column: 'animal_portrait'
[03:33:57] [INFO] |-- 🖼️ column: 'edited_portrait'
[03:33:57] [INFO] 🏆 Preview complete!
for i in range(len(preview.dataset)):
preview.display_sample_record()
Generated Columns ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Name ┃ Value ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ animal │ owl │ ├───────────────────────────────┼────────────────────────────────────────────────────────────────────────────┤ │ accessory │ a chef hat │ ├───────────────────────────────┼────────────────────────────────────────────────────────────────────────────┤ │ setting │ a tropical beach at sunset │ ├───────────────────────────────┼────────────────────────────────────────────────────────────────────────────┤ │ art_style │ a photorealistic style │ └───────────────────────────────┴────────────────────────────────────────────────────────────────────────────┘ Images ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Name ┃ Preview ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ animal_portrait │ [0] <base64, 1807532 chars> │ ├────────────────────────────────────────┼───────────────────────────────────────────────────────────────────┤ │ edited_portrait │ [0] <base64, 1700460 chars> │ └────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘
Generated Columns ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Name ┃ Value ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ animal │ rabbit │ ├───────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤ │ accessory │ a tiny top hat │ ├───────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤ │ setting │ a cozy living room │ ├───────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤ │ art_style │ a watercolor painting │ └───────────────────────────────────┴────────────────────────────────────────────────────────────────────────┘ Images ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Name ┃ Preview ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ animal_portrait │ [0] <base64, 1822872 chars> │ ├────────────────────────────────────────┼───────────────────────────────────────────────────────────────────┤ │ edited_portrait │ [0] <base64, 2102016 chars> │ └────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘
preview.dataset
| animal | accessory | setting | art_style | animal_portrait | edited_portrait | |
|---|---|---|---|---|---|---|
| 0 | owl | a chef hat | a tropical beach at sunset | a photorealistic style | [iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAIAAAA12IJaA... | [iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAIAAAA12IJaA... |
| 1 | rabbit | a tiny top hat | a cozy living room | a watercolor painting | [iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAIAAAA12IJaA... | [iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAIAAAA12IJaA... |
🔎 Compare original vs edited¶
Let's display the generated animal portraits next to their edited versions.
def display_image(image_value, base_path: Path | None = None) -> None:
"""Display an image from base64 (preview mode) or file path (create mode)."""
values = [image_value] if isinstance(image_value, str) else list(image_value)
for value in values:
if base_path is not None:
display(IPImage(filename=str(base_path / value)))
else:
display(IPImage(data=base64.b64decode(value)))
def display_before_after(row, index: int, base_path: Path | None = None) -> None:
"""Display original portrait vs edited version for a single record."""
print(f"\n{'=' * 60}")
print(f"Record {index}: {row['animal']} wearing {row['accessory']}")
print(f"Setting: {row['setting']}, Style: {row['art_style']}")
print(f"{'=' * 60}")
print("\n📷 Generated portrait:")
display_image(row["animal_portrait"], base_path)
print("\n🎨 Edited version:")
display_image(row["edited_portrait"], base_path)
for index, row in preview.dataset.iterrows():
display_before_after(row, index)
============================================================ Record 0: owl wearing a chef hat Setting: a tropical beach at sunset, Style: a photorealistic style ============================================================ 📷 Generated portrait:
🎨 Edited version:
============================================================ Record 1: rabbit wearing a tiny top hat Setting: a cozy living room, Style: a watercolor painting ============================================================ 📷 Generated portrait:
🎨 Edited version:
🆙 Create at scale¶
In create mode, images are saved to disk in images/<column_name>/ folders with UUID filenames. The dataframe stores relative paths. ImageContext auto-detection handles this transparently—generated file paths are resolved to base64 before being sent to the model for editing.
results = data_designer.create(config_builder, num_records=5, dataset_name="tutorial-6-edited-images")
[03:33:58] [INFO] 🎨 Creating Data Designer dataset
[03:33:58] [INFO] |-- 🔒 Jinja rendering engine: secure
[03:33:58] [INFO] ✅ Validation passed
[03:33:58] [INFO] ⛓️ Sorting column configs into a Directed Acyclic Graph
[03:33:58] [INFO] 🩺 Running health checks for models...
[03:33:58] [INFO] |-- 👀 Checking 'black-forest-labs/flux.2-pro' in provider named 'openrouter' for model alias 'image-model'...
[03:34:06] [INFO] |-- ✅ Passed!
[03:34:06] [INFO] ⏳ Processing batch 1 of 1
[03:34:06] [INFO] 🎲 Preparing samplers to generate 5 records across 4 columns
[03:34:06] [INFO] 🖼️ image model config for column 'animal_portrait'
[03:34:06] [INFO] |-- model: 'black-forest-labs/flux.2-pro'
[03:34:06] [INFO] |-- model alias: 'image-model'
[03:34:06] [INFO] |-- model provider: 'openrouter'
[03:34:06] [INFO] |-- inference parameters:
[03:34:06] [INFO] | |-- generation_type=image
[03:34:06] [INFO] | |-- max_parallel_requests=4
[03:34:06] [INFO] | |-- extra_body={'height': 512, 'width': 512}
[03:34:06] [INFO] ⚡️ Processing image column 'animal_portrait' with 4 concurrent workers
[03:34:06] [INFO] ⏱️ image column 'animal_portrait' will report progress after each record
[03:34:15] [INFO] |-- 🥚 image column 'animal_portrait' progress: 1/5 (20%) complete, 1 ok, 0 failed, 0.11 rec/s, eta 36.9s
[03:34:16] [INFO] |-- 🐣 image column 'animal_portrait' progress: 2/5 (40%) complete, 2 ok, 0 failed, 0.21 rec/s, eta 14.1s
[03:34:16] [INFO] |-- 🐥 image column 'animal_portrait' progress: 3/5 (60%) complete, 3 ok, 0 failed, 0.30 rec/s, eta 6.7s
[03:34:17] [INFO] |-- 🐤 image column 'animal_portrait' progress: 4/5 (80%) complete, 4 ok, 0 failed, 0.37 rec/s, eta 2.7s
[03:34:26] [INFO] |-- 🐔 image column 'animal_portrait' progress: 5/5 (100%) complete, 5 ok, 0 failed, 0.25 rec/s, eta 0.0s
[03:34:26] [INFO] 🖼️ image model config for column 'edited_portrait'
[03:34:26] [INFO] |-- model: 'black-forest-labs/flux.2-pro'
[03:34:26] [INFO] |-- model alias: 'image-model'
[03:34:26] [INFO] |-- model provider: 'openrouter'
[03:34:26] [INFO] |-- inference parameters:
[03:34:26] [INFO] | |-- generation_type=image
[03:34:26] [INFO] | |-- max_parallel_requests=4
[03:34:26] [INFO] | |-- extra_body={'height': 512, 'width': 512}
[03:34:26] [INFO] ⚡️ Processing image column 'edited_portrait' with 4 concurrent workers
[03:34:26] [INFO] ⏱️ image column 'edited_portrait' will report progress after each record
[03:34:38] [INFO] |-- 🌧️ image column 'edited_portrait' progress: 1/5 (20%) complete, 1 ok, 0 failed, 0.09 rec/s, eta 45.4s
[03:34:38] [INFO] |-- 🌦️ image column 'edited_portrait' progress: 2/5 (40%) complete, 2 ok, 0 failed, 0.17 rec/s, eta 17.6s
[03:34:39] [INFO] |-- ⛅ image column 'edited_portrait' progress: 3/5 (60%) complete, 3 ok, 0 failed, 0.24 rec/s, eta 8.5s
[03:34:42] [INFO] |-- 🌤️ image column 'edited_portrait' progress: 4/5 (80%) complete, 4 ok, 0 failed, 0.26 rec/s, eta 3.9s
[03:34:51] [INFO] |-- ☀️ image column 'edited_portrait' progress: 5/5 (100%) complete, 5 ok, 0 failed, 0.20 rec/s, eta 0.0s
[03:34:51] [INFO] 📊 Model usage summary:
[03:34:51] [INFO] |-- model: black-forest-labs/flux.2-pro
[03:34:51] [INFO] |-- tokens: input=7655, output=0, total=7655, tps=170
[03:34:51] [INFO] |-- requests: success=10, failed=0, total=10, rpm=13
[03:34:51] [INFO] |-- images: total=10
[03:34:51] [INFO] 📐 Measuring dataset column statistics:
[03:34:51] [INFO] |-- 🎲 column: 'animal'
[03:34:51] [INFO] |-- 🎲 column: 'accessory'
[03:34:51] [INFO] |-- 🎲 column: 'setting'
[03:34:51] [INFO] |-- 🎲 column: 'art_style'
[03:34:51] [INFO] |-- 🖼️ column: 'animal_portrait'
[03:34:51] [INFO] |-- 🖼️ column: 'edited_portrait'
dataset = results.load_dataset()
dataset.head()
| animal | accessory | setting | art_style | animal_portrait | edited_portrait | |
|---|---|---|---|---|---|---|
| 0 | dog | oversized sunglasses | a cozy living room | a Disney Pixar 3D render | ['images/animal_portrait/dd24768e-c973-47b9-be... | ['images/edited_portrait/98ca2391-2268-483e-a8... |
| 1 | fox | oversized sunglasses | a holiday card backdrop with snowflakes | a photorealistic style | ['images/animal_portrait/20cb75cb-d64b-4cb2-98... | ['images/edited_portrait/d0bee72b-65c8-4df5-8e... |
| 2 | owl | a knitted beanie | a red carpet event | a pop art poster | ['images/animal_portrait/b99aae74-3f60-4661-9c... | ['images/edited_portrait/21fe45f3-522d-47ca-b3... |
| 3 | dog | a chef hat | a cozy living room | a watercolor painting | ['images/animal_portrait/e45b2efd-bd13-46f2-8f... | ['images/edited_portrait/6d762af7-d965-4f4b-96... |
| 4 | dog | a monocle and mustache | a photo studio with soft lighting | a watercolor painting | ['images/animal_portrait/2918bd59-6709-4be3-91... | ['images/edited_portrait/b6e9b096-3b4b-4e3e-b4... |
for index, row in dataset.head(10).iterrows():
display_before_after(row, index, base_path=results.artifact_storage.base_dataset_path)
============================================================ Record 0: dog wearing oversized sunglasses Setting: a cozy living room, Style: a Disney Pixar 3D render ============================================================ 📷 Generated portrait:
🎨 Edited version:
============================================================ Record 1: fox wearing oversized sunglasses Setting: a holiday card backdrop with snowflakes, Style: a photorealistic style ============================================================ 📷 Generated portrait:
🎨 Edited version:
============================================================ Record 2: owl wearing a knitted beanie Setting: a red carpet event, Style: a pop art poster ============================================================ 📷 Generated portrait:
🎨 Edited version:
============================================================ Record 3: dog wearing a chef hat Setting: a cozy living room, Style: a watercolor painting ============================================================ 📷 Generated portrait:
🎨 Edited version:
============================================================ Record 4: dog wearing a monocle and mustache Setting: a photo studio with soft lighting, Style: a watercolor painting ============================================================ 📷 Generated portrait:
🎨 Edited version:
⏭️ Next steps¶
- Experiment with different autoregressive models for image generation and editing
- Try more creative editing prompts (style transfer, background replacement, artistic filters)
- Combine image generation with text generation (e.g., generate captions using an LLM-Text column with
ImageContext) - Chain more than two image columns for multi-step editing pipelines
Related tutorials:
- The basics: samplers and LLM text columns
- Providing images as context: image-to-text with VLMs
- Generating images: text-to-image generation with diffusion models