Tutorials

Generating Images

View as Markdown
Run in Google Colab

🎨 Data Designer Tutorial: Generating Images

📚 What you'll learn

This notebook shows how to generate synthetic image data with Data Designer using image-generation models.

  • 🖼️ Image generation columns: Add columns that produce images from text prompts
  • 📝 Jinja2 prompts: Drive diversity by referencing other columns in your prompt template
  • 💾 Preview vs create: Preview stores base64 in the dataframe; create saves images to disk and stores paths

Data Designer supports both diffusion (e.g. DALL·E, Stable Diffusion, Imagen) and autoregressive (e.g. Gemini image, GPT image) models.

Prerequisites: This tutorial uses OpenRouter with the Flux 2 Pro image 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.
Python
1from IPython.display import Image as IPImage
2from IPython.display import display
3 
4import data_designer.config as dd
5from data_designer.interface import DataDesigner
6

⚙️ Initialize the Data Designer interface

We initialize Data Designer without arguments here—the image model is configured explicitly in the next cell. No default text model is needed for this tutorial.

Python
1data_designer = DataDesigner()
2

🎛️ Define an image-generation model

  • Use ImageInferenceParams so Data Designer treats this model as an image generator.
  • Image options (size, quality, aspect ratio, etc.) are model-specific; pass them via extra_body.
Python
1MODEL_PROVIDER = "openrouter"
2MODEL_ID = "black-forest-labs/flux.2-pro"
3MODEL_ALIAS = "image-model"
4 
5model_configs = [
6    dd.ModelConfig(
7        alias=MODEL_ALIAS,
8        model=MODEL_ID,
9        provider=MODEL_PROVIDER,
10        inference_parameters=dd.ImageInferenceParams(
11            extra_body={"height": 512, "width": 512},
12        ),
13    )
14]
15

🏗️ Build the config: samplers + image column

We'll generate diverse dog portrait images: sampler columns drive subject (breed), age, style, look direction, and emotion. The image-generation column uses a Jinja2 prompt that references all of them.

Python
1config_builder = dd.DataDesignerConfigBuilder(model_configs=model_configs)
2 
3config_builder.add_column(
4    dd.SamplerColumnConfig(
5        name="style",
6        sampler_type=dd.SamplerType.CATEGORY,
7        params=dd.CategorySamplerParams(
8            values=[
9                "photorealistic",
10                "oil painting",
11                "watercolor",
12                "digital art",
13                "sketch",
14                "anime",
15            ],
16        ),
17    )
18)
19 
20config_builder.add_column(
21    dd.SamplerColumnConfig(
22        name="dog_breed",
23        sampler_type=dd.SamplerType.CATEGORY,
24        params=dd.CategorySamplerParams(
25            values=[
26                "a Golden Retriever",
27                "a German Shepherd",
28                "a Labrador Retriever",
29                "a Bulldog",
30                "a Beagle",
31                "a Poodle",
32                "a Corgi",
33                "a Siberian Husky",
34                "a Dalmatian",
35                "a Yorkshire Terrier",
36                "a Boxer",
37                "a Dachshund",
38                "a Doberman Pinscher",
39                "a Shih Tzu",
40                "a Chihuahua",
41                "a Border Collie",
42                "an Australian Shepherd",
43                "a Cocker Spaniel",
44                "a Maltese",
45                "a Pomeranian",
46                "a Saint Bernard",
47                "a Great Dane",
48                "an Akita",
49                "a Samoyed",
50                "a Boston Terrier",
51            ],
52        ),
53    )
54)
55 
56config_builder.add_column(
57    dd.SamplerColumnConfig(
58        name="cat_breed",
59        sampler_type=dd.SamplerType.CATEGORY,
60        params=dd.CategorySamplerParams(
61            values=[
62                "a Persian",
63                "a Maine Coon",
64                "a Siamese",
65                "a Ragdoll",
66                "a Bengal",
67                "an Abyssinian",
68                "a British Shorthair",
69                "a Sphynx",
70                "a Scottish Fold",
71                "a Russian Blue",
72                "a Birman",
73                "an Oriental Shorthair",
74                "a Norwegian Forest Cat",
75                "a Devon Rex",
76                "a Burmese",
77                "an Egyptian Mau",
78                "a Tonkinese",
79                "a Himalayan",
80                "a Savannah",
81                "a Chartreux",
82                "a Somali",
83                "a Manx",
84                "a Turkish Angora",
85                "a Balinese",
86                "an American Shorthair",
87            ],
88        ),
89    )
90)
91 
92config_builder.add_column(
93    dd.SamplerColumnConfig(
94        name="dog_age",
95        sampler_type=dd.SamplerType.CATEGORY,
96        params=dd.CategorySamplerParams(
97            values=["1-3", "3-6", "6-9", "9-12", "12-15"],
98        ),
99    )
100)
101 
102config_builder.add_column(
103    dd.SamplerColumnConfig(
104        name="cat_age",
105        sampler_type=dd.SamplerType.CATEGORY,
106        params=dd.CategorySamplerParams(
107            values=["1-3", "3-6", "6-9", "9-12", "12-18"],
108        ),
109    )
110)
111 
112config_builder.add_column(
113    dd.SamplerColumnConfig(
114        name="dog_look_direction",
115        sampler_type=dd.SamplerType.CATEGORY,
116        params=dd.CategorySamplerParams(
117            values=["left", "right", "front", "up", "down"],
118        ),
119    )
120)
121 
122config_builder.add_column(
123    dd.SamplerColumnConfig(
124        name="cat_look_direction",
125        sampler_type=dd.SamplerType.CATEGORY,
126        params=dd.CategorySamplerParams(
127            values=["left", "right", "front", "up", "down"],
128        ),
129    )
130)
131 
132config_builder.add_column(
133    dd.SamplerColumnConfig(
134        name="dog_emotion",
135        sampler_type=dd.SamplerType.CATEGORY,
136        params=dd.CategorySamplerParams(
137            values=["happy", "curious", "serious", "sleepy", "excited"],
138        ),
139    )
140)
141 
142config_builder.add_column(
143    dd.SamplerColumnConfig(
144        name="cat_emotion",
145        sampler_type=dd.SamplerType.CATEGORY,
146        params=dd.CategorySamplerParams(
147            values=["aloof", "curious", "content", "sleepy", "playful"],
148        ),
149    )
150)
151 
152config_builder.add_column(
153    dd.ImageColumnConfig(
154        name="generated_image",
155        prompt=(
156            """
157A {{ style }} family pet portrait of a {{ dog_breed }} dog of {{ dog_age }} years old looking {{dog_look_direction}} with an {{ dog_emotion }} expression and
158{{ cat_breed }} cat of {{ cat_age }} years old looking {{ cat_look_direction }} with an {{ cat_emotion }} expression in the background. Both subjects should be in focus.
159        """
160        ),
161        model_alias=MODEL_ALIAS,
162    )
163)
164 
165data_designer.validate(config_builder)
166
Output
[21:20:32] [INFO] ✅ Validation passed

🔁 Preview: images as base64

In preview mode, generated images are stored as base64 strings in the dataframe. Run the next cell to step through each record (images are shown in the sample record display, but only in a notebook environment).

Python
1preview = data_designer.preview(config_builder, num_records=2)
2
Output
[21:20:32] [INFO] 🔁 Preview generation in progress
[21:20:32] [INFO]   |-- 🔒 Jinja rendering engine: secure
[21:20:32] [INFO] ✅ Validation passed
[21:20:32] [INFO] ⛓️ Sorting column configs into a Directed Acyclic Graph
[21:20:32] [INFO] 🩺 Running health checks for models...
[21:20:32] [INFO]   |-- 👀 Checking 'black-forest-labs/flux.2-pro' in provider named 'openrouter' for model alias 'image-model'...
[21:20:43] [INFO]   |-- ✅ Passed!
[21:20:43] [INFO] ⚡ DATA_DESIGNER_ASYNC_ENGINE is enabled - using async task-queue preview
[21:20:43] [INFO] 🖼️ image model config for column 'generated_image'
[21:20:43] [INFO]   |-- model: 'black-forest-labs/flux.2-pro'
[21:20:43] [INFO]   |-- model alias: 'image-model'
[21:20:43] [INFO]   |-- model provider: 'openrouter'
[21:20:43] [INFO]   |-- inference parameters:
[21:20:43] [INFO]   |  |-- generation_type=image
[21:20:43] [INFO]   |  |-- max_parallel_requests=4
[21:20:43] [INFO]   |  |-- extra_body={'height': 512, 'width': 512}
[21:20:43] [INFO] ⚡️ Async generation: 1 column(s) (generated_image), 2 tasks across 1 row group(s)
[21:20:43] [INFO] 🚀 (1/1) Dispatching with 2 records
[21:20:43] [INFO] 🎲 (1/1) Preparing samplers to generate 2 records across 9 columns
[21:20:56] [INFO] 📊 Progress [13.2s]:
[21:20:56] [INFO]   |-- 🚗 generated_image: 1/2 (50%) 0.1 rec/s
[21:20:57] [INFO] 📊 Progress [13.9s]:
[21:20:57] [INFO]   |-- 🚀 generated_image: 2/2 (100%) 0.1 rec/s
[21:20:57] [INFO] ✅ Async generation complete [13.9s]: 2 ok, 0 failed across 1 column(s)
[21:20:57] [INFO] 📊 Model usage summary:
[21:20:57] [INFO]   |-- model: black-forest-labs/flux.2-pro
[21:20:57] [INFO]   |-- tokens: input=135, output=6144, total=6279, tps=453
[21:20:57] [INFO]   |-- requests: success=2, failed=0, total=2, rpm=8
[21:20:57] [INFO]   |-- images: total=2
[21:20:57] [INFO] 📐 Measuring dataset column statistics:
[21:20:57] [INFO]   |-- 🎲 column: 'style'
[21:20:57] [INFO]   |-- 🎲 column: 'dog_breed'
[21:20:57] [INFO]   |-- 🎲 column: 'cat_breed'
[21:20:57] [INFO]   |-- 🎲 column: 'dog_age'
[21:20:57] [INFO]   |-- 🎲 column: 'cat_age'
[21:20:57] [INFO]   |-- 🎲 column: 'dog_look_direction'
[21:20:57] [INFO]   |-- 🎲 column: 'cat_look_direction'
[21:20:57] [INFO]   |-- 🎲 column: 'dog_emotion'
[21:20:57] [INFO]   |-- 🎲 column: 'cat_emotion'
[21:20:57] [INFO]   |-- 🖼️ column: 'generated_image'
[21:20:57] [INFO] ☀️ Preview complete!
Python
1for i in range(len(preview.dataset)):
2    preview.display_sample_record()
3
Output
[index: 0]
                                                                                                              
                                              Generated Columns                                               
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                                    ┃ Value                                            ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ style                                                   │ watercolor                                       │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ dog_breed                                               │ a Cocker Spaniel                                 │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ cat_breed                                               │ a Turkish Angora                                 │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ dog_age                                                 │ 12-15                                            │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ cat_age                                                 │ 9-12                                             │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ dog_look_direction                                      │ left                                             │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ cat_look_direction                                      │ up                                               │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ dog_emotion                                             │ serious                                          │
├─────────────────────────────────────────────────────────┼──────────────────────────────────────────────────┤
│ cat_emotion                                             │ curious                                          │
└─────────────────────────────────────────────────────────┴──────────────────────────────────────────────────┘
                                                                                                              
                                                                                                              
                                                    Images                                                    
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                   ┃ Preview                                                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ generated_image                        │ [0] <base64, 1935356 chars>                                       │
└────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘
🖼️ generated_image[0]
[index: 1]
                                                                                                              
                                              Generated Columns                                               
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                                       ┃ Value                                         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ style                                                      │ watercolor                                    │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ dog_breed                                                  │ a Dachshund                                   │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ cat_breed                                                  │ a Russian Blue                                │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ dog_age                                                    │ 12-15                                         │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ cat_age                                                    │ 3-6                                           │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ dog_look_direction                                         │ front                                         │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ cat_look_direction                                         │ front                                         │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ dog_emotion                                                │ excited                                       │
├────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ cat_emotion                                                │ sleepy                                        │
└────────────────────────────────────────────────────────────┴───────────────────────────────────────────────┘
                                                                                                              
                                                                                                              
                                                    Images                                                    
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                   ┃ Preview                                                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ generated_image                        │ [0] <base64, 1968664 chars>                                       │
└────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘
🖼️ generated_image[0]
Python
1preview.dataset
2
Output
style dog_breed cat_breed dog_age cat_age dog_look_direction cat_look_direction dog_emotion cat_emotion generated_image
0 watercolor a Cocker Spaniel a Turkish Angora 12-15 9-12 left up serious curious [iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAIAAAA12IJaA...
1 watercolor a Dachshund a Russian Blue 12-15 3-6 front front excited sleepy [iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAIAAAA12IJaA...

🆙 Create: images saved to disk

In create mode, images are written to an images/ folder with UUID filenames; the dataframe stores relative paths (e.g. images/1d16b6e2-562f-4f51-91e5-baaa999ea916.png).

Python
1results = data_designer.create(config_builder, num_records=2, dataset_name="tutorial-5-images")
2
Output
[21:20:57] [INFO] 🎨 Creating Data Designer dataset
[21:20:57] [INFO]   |-- 🔒 Jinja rendering engine: secure
[21:20:57] [INFO] ✅ Validation passed
[21:20:57] [INFO] ⛓️ Sorting column configs into a Directed Acyclic Graph
[21:20:57] [INFO] 🩺 Running health checks for models...
[21:20:57] [INFO]   |-- 👀 Checking 'black-forest-labs/flux.2-pro' in provider named 'openrouter' for model alias 'image-model'...
[21:21:08] [INFO]   |-- ✅ Passed!
[21:21:08] [INFO] ⚡ DATA_DESIGNER_ASYNC_ENGINE is enabled - using async task-queue builder
[21:21:08] [INFO] 🖼️ image model config for column 'generated_image'
[21:21:08] [INFO]   |-- model: 'black-forest-labs/flux.2-pro'
[21:21:08] [INFO]   |-- model alias: 'image-model'
[21:21:08] [INFO]   |-- model provider: 'openrouter'
[21:21:08] [INFO]   |-- inference parameters:
[21:21:08] [INFO]   |  |-- generation_type=image
[21:21:08] [INFO]   |  |-- max_parallel_requests=4
[21:21:08] [INFO]   |  |-- extra_body={'height': 512, 'width': 512}
[21:21:08] [INFO] ⚡️ Async generation: 1 column(s) (generated_image), 2 tasks across 1 row group(s)
[21:21:08] [INFO] 🚀 (1/1) Dispatching with 2 records
[21:21:08] [INFO] 🎲 (1/1) Preparing samplers to generate 2 records across 9 columns
[21:21:20] [INFO] 📊 Progress [11.9s]:
[21:21:20] [INFO]   |-- 😐 generated_image: 1/2 (50%) 0.1 rec/s
[21:21:21] [INFO] 📊 Progress [12.9s]:
[21:21:21] [INFO]   |-- 🤩 generated_image: 2/2 (100%) 0.2 rec/s
[21:21:21] [INFO] ✅ Async generation complete [12.9s]: 2 ok, 0 failed across 1 column(s)
[21:21:21] [INFO] 📊 Model usage summary:
[21:21:21] [INFO]   |-- model: black-forest-labs/flux.2-pro
[21:21:21] [INFO]   |-- tokens: input=135, output=6144, total=6279, tps=479
[21:21:21] [INFO]   |-- requests: success=2, failed=0, total=2, rpm=9
[21:21:21] [INFO]   |-- images: total=2
[21:21:21] [INFO] 📐 Measuring dataset column statistics:
[21:21:21] [INFO]   |-- 🎲 column: 'style'
[21:21:21] [INFO]   |-- 🎲 column: 'dog_breed'
[21:21:21] [INFO]   |-- 🎲 column: 'cat_breed'
[21:21:21] [INFO]   |-- 🎲 column: 'dog_age'
[21:21:21] [INFO]   |-- 🎲 column: 'cat_age'
[21:21:21] [INFO]   |-- 🎲 column: 'dog_look_direction'
[21:21:21] [INFO]   |-- 🎲 column: 'cat_look_direction'
[21:21:21] [INFO]   |-- 🎲 column: 'dog_emotion'
[21:21:21] [INFO]   |-- 🎲 column: 'cat_emotion'
[21:21:21] [INFO]   |-- 🖼️ column: 'generated_image'
Python
1dataset = results.load_dataset()
2dataset.head()
3
Output
style dog_breed cat_breed dog_age cat_age dog_look_direction cat_look_direction dog_emotion cat_emotion generated_image
0 oil painting a Labrador Retriever a Balinese 3-6 6-9 front down excited playful ['images/generated_image/68b21d2f-9e49-4571-88...
1 anime a Border Collie a Norwegian Forest Cat 3-6 6-9 down down serious aloof ['images/generated_image/36126bd1-9f23-4fa5-b4...
Python
1# Display all images from the created dataset. Paths are relative to the artifact output directory.
2for index, row in dataset.iterrows():
3    path_or_list = row.get("generated_image")
4    if path_or_list is not None:
5        paths = path_or_list if not isinstance(path_or_list, str) else [path_or_list]
6        for path in paths:
7            full_path = results.artifact_storage.base_dataset_path / path
8            display(IPImage(filename=str(full_path)))
9
Output
OutputOutput

⏭️ Next steps