🎨 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 ImageContext to 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_KEY in 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.config provides the configuration API.
DataDesigner is the main interface for generation.

In [1]:

Copied!





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

In [2]:

Copied!

data_designer = DataDesigner()
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 ImageInferenceParams so 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_KEY in your environment.

In [3]:

Copied!





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},
        ),
    )
]
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

In [4]:

Copied!





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)
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)

[12:19:07] [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.

In [5]:

Copied!

preview = data_designer.preview(config_builder, num_records=2)
preview = data_designer.preview(config_builder, num_records=2)

[12:19:07] [INFO] 👁️ Preview generation in progress

[12:19:07] [INFO] ✅ Validation passed

[12:19:08] [INFO] ⛓️ Sorting column configs into a Directed Acyclic Graph

[12:19:08] [INFO] 🩺 Running health checks for models...

[12:19:08] [INFO]   |-- 👀 Checking 'black-forest-labs/flux.2-pro' in provider named 'openrouter' for model alias 'image-model'...

[12:19:17] [INFO]   |-- ✅ Passed!

[12:19:17] [INFO] 🎲 Preparing samplers to generate 2 records across 4 columns

[12:19:17] [INFO] 🖼️ image model config for column 'animal_portrait'

[12:19:17] [INFO]   |-- model: 'black-forest-labs/flux.2-pro'

[12:19:17] [INFO]   |-- model alias: 'image-model'

[12:19:17] [INFO]   |-- model provider: 'openrouter'

[12:19:17] [INFO]   |-- inference parameters:

[12:19:17] [INFO]   |  |-- generation_type=image

[12:19:17] [INFO]   |  |-- max_parallel_requests=4

[12:19:17] [INFO]   |  |-- extra_body={'height': 512, 'width': 512}

[12:19:17] [INFO] ⚡️ Processing image column 'animal_portrait' with 4 concurrent workers

[12:19:17] [INFO] ⏱️ image column 'animal_portrait' will report progress after each record

[12:19:25] [INFO]   |-- 😐 image column 'animal_portrait' progress: 1/2 (50%) complete, 1 ok, 0 failed, 0.13 rec/s, eta 7.9s

[12:19:27] [INFO]   |-- 🤩 image column 'animal_portrait' progress: 2/2 (100%) complete, 2 ok, 0 failed, 0.20 rec/s, eta 0.0s

[12:19:27] [INFO] 🖼️ image model config for column 'edited_portrait'

[12:19:27] [INFO]   |-- model: 'black-forest-labs/flux.2-pro'

[12:19:27] [INFO]   |-- model alias: 'image-model'

[12:19:27] [INFO]   |-- model provider: 'openrouter'

[12:19:27] [INFO]   |-- inference parameters:

[12:19:27] [INFO]   |  |-- generation_type=image

[12:19:27] [INFO]   |  |-- max_parallel_requests=4

[12:19:27] [INFO]   |  |-- extra_body={'height': 512, 'width': 512}

[12:19:27] [INFO] ⚡️ Processing image column 'edited_portrait' with 4 concurrent workers

[12:19:27] [INFO] ⏱️ image column 'edited_portrait' will report progress after each record

[12:19:41] [INFO]   |-- ⛅ image column 'edited_portrait' progress: 1/2 (50%) complete, 1 ok, 0 failed, 0.08 rec/s, eta 13.3s

[12:19:42] [INFO]   |-- ☀️ image column 'edited_portrait' progress: 2/2 (100%) complete, 2 ok, 0 failed, 0.14 rec/s, eta 0.0s

[12:19:42] [INFO] 📊 Model usage summary:

[12:19:42] [INFO]   |-- model: black-forest-labs/flux.2-pro

[12:19:42] [INFO]   |-- tokens: input=0, output=0, total=0, tps=0

[12:19:42] [INFO]   |-- requests: success=4, failed=0, total=4, rpm=9

[12:19:42] [INFO]   |-- images: total=4

[12:19:42] [INFO] 📐 Measuring dataset column statistics:

[12:19:42] [INFO]   |-- 🎲 column: 'animal'

[12:19:42] [INFO]   |-- 🎲 column: 'accessory'

[12:19:42] [INFO]   |-- 🎲 column: 'setting'

[12:19:42] [INFO]   |-- 🎲 column: 'art_style'

[12:19:42] [INFO]   |-- 🖼️ column: 'animal_portrait'

[12:19:42] [INFO]   |-- 🖼️ column: 'edited_portrait'

[12:19:42] [INFO] 🎆 Preview complete!

In [6]:

Copied!

for i in range(len(preview.dataset)):
    preview.display_sample_record()
for i in range(len(preview.dataset)):
    preview.display_sample_record()

[index: 0]

                                                                                                              
                                              Generated Columns                                               
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                 ┃ Value                                                               ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ animal                               │ owl                                                                 │
├──────────────────────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ accessory                            │ a tiny top hat                                                      │
├──────────────────────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ setting                              │ a red carpet event                                                  │
├──────────────────────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ art_style                            │ a pop art poster                                                    │
└──────────────────────────────────────┴─────────────────────────────────────────────────────────────────────┘
                                                                                                              
                                                                                                              
                                                    Images                                                    
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                   ┃ Preview                                                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ animal_portrait                        │ [0] <base64, 1713836 chars>                                       │
├────────────────────────────────────────┼───────────────────────────────────────────────────────────────────┤
│ edited_portrait                        │ [0] <base64, 2175740 chars>                                       │
└────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘

🖼️ animal_portrait[0]

No description has been provided for this image

🖼️ edited_portrait[0]

[index: 1]

                                                                                                              
                                              Generated Columns                                               
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                           ┃ Value                                                                     ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ animal                         │ fox                                                                       │
├────────────────────────────────┼───────────────────────────────────────────────────────────────────────────┤
│ accessory                      │ a tiny top hat                                                            │
├────────────────────────────────┼───────────────────────────────────────────────────────────────────────────┤
│ setting                        │ a red carpet event                                                        │
├────────────────────────────────┼───────────────────────────────────────────────────────────────────────────┤
│ art_style                      │ a Disney Pixar 3D render                                                  │
└────────────────────────────────┴───────────────────────────────────────────────────────────────────────────┘
                                                                                                              
                                                                                                              
                                                    Images                                                    
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                   ┃ Preview                                                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ animal_portrait                        │ [0] <base64, 1822088 chars>                                       │
├────────────────────────────────────────┼───────────────────────────────────────────────────────────────────┤
│ edited_portrait                        │ [0] <base64, 1800368 chars>                                       │
└────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘

🖼️ animal_portrait[0]