cvpal.generate Module

The cvpal.generate module provides functions for creating synthetic images from text prompts, enabling data augmentation and expanding your training datasets with AI-generated content.

Open Source Module

This is part of the open-source cvpal Python package. For platform API endpoints, see the Platform API Reference.

Installation

The generate module is included with the cvpal package:

bash

pip install cvpal

Import

python

from cvpal import generate

Functions

synthetic_images

Generate synthetic images from text prompts using AI models. Perfect for data augmentation and expanding your training datasets.

Function Signature

python

generate.synthetic_images(
    prompt: str,
    num_images: int = 1,
    style: str = "photorealistic",
    resolution: str = "1024x1024",
    quality: str = "high"
) -> List[str]

Parameters

Parameter	Type	Default	Description
prompt	str	-	Text description of the image to generate
num_images	int	1	Number of images to generate (1-50)
style	str	"photorealistic"	Image style: "photorealistic", "artistic", "sketch", "cartoon"
resolution	str	"1024x1024"	Image resolution: "512x512", "1024x1024", "2048x2048"
quality	str	"high"	Generation quality: "standard", "high", "ultra"

Returns

List[str] - List of file paths to the generated images

Example

python

from cvpal import generate

# Generate a single photorealistic image
images = generate.synthetic_images("a cat sitting on a wooden chair")
print(f"Generated image: {images[0]}")

# Generate multiple artistic images
artistic_images = generate.synthetic_images(
    prompt="sunset over mountains with lake reflection",
    num_images=5,
    style="artistic",
    resolution="2048x2048",
    quality="ultra"
)

print(f"Generated {len(artistic_images)} artistic images")

batch_generate

Generate multiple images with different prompts in a single batch operation for efficient processing.

Function Signature

python

generate.batch_generate(
    prompts: List[str],
    style: str = "photorealistic",
    resolution: str = "1024x1024",
    quality: str = "high"
) -> Dict[str, List[str]]

Parameters

Parameter	Type	Description
prompts	List[str]	List of text prompts for image generation
style	str	Image style for all generated images
resolution	str	Resolution for all generated images
quality	str	Quality setting for all generated images

Returns

Dict[str, List[str]] - Dictionary mapping each prompt to its generated image paths

Example

python

from cvpal import generate

# Batch generate images for different scenarios
prompts = [
    "person walking on street during daytime",
    "person walking on street at night",
    "person running in park",
    "person sitting on bench"
]

results = generate.batch_generate(
    prompts=prompts,
    style="photorealistic",
    resolution="1024x1024"
)

# Access generated images for each prompt
for prompt, image_paths in results.items():
    print(f"Prompt: {prompt}")
    print(f"Generated {len(image_paths)} images")
    for path in image_paths:
        print(f"  - {path}")

generate_with_variations

Generate multiple variations of the same prompt with slight modifications for data augmentation.

Function Signature

python

generate.generate_with_variations(
    base_prompt: str,
    num_variations: int = 5,
    variation_strength: float = 0.3,
    style: str = "photorealistic"
) -> List[str]

Parameters

Parameter	Type	Default	Description
base_prompt	str	-	Base text prompt to generate variations from
num_variations	int	5	Number of variations to generate (1-20)
variation_strength	float	0.3	Strength of variations (0.1-1.0)
style	str	"photorealistic"	Image style for all variations

Returns

List[str] - List of file paths to the generated variation images

Example

python

from cvpal import generate

# Generate variations of a base prompt for data augmentation
base_prompt = "a red car parked on the street"

variations = generate.generate_with_variations(
    base_prompt=base_prompt,
    num_variations=8,
    variation_strength=0.4,
    style="photorealistic"
)

print(f"Generated {len(variations)} variations of: {base_prompt}")
for i, path in enumerate(variations):
    print(f"Variation {i+1}: {path}")

Complete Example

Here's a complete example showing how to use the generate module for data augmentation:

python

from cvpal import generate
import os

def augment_dataset_with_synthetic_images(base_prompts, output_dir):
    """
    Generate synthetic images to augment an existing dataset
    """
    os.makedirs(output_dir, exist_ok=True)
    
    # Generate base synthetic images
    print("Generating base synthetic images...")
    for prompt in base_prompts:
        images = generate.synthetic_images(
            prompt=prompt,
            num_images=3,
            style="photorealistic",
            resolution="1024x1024"
        )
        print(f"Generated {len(images)} images for: {prompt}")
    
    # Generate variations for data augmentation
    print("\nGenerating variations for data augmentation...")
    for prompt in base_prompts:
        variations = generate.generate_with_variations(
            base_prompt=prompt,
            num_variations=5,
            variation_strength=0.3
        )
        print(f"Generated {len(variations)} variations for: {prompt}")
    
    # Batch generate with different styles
    print("\nGenerating images in different styles...")
    styles = ["photorealistic", "artistic", "sketch"]
    for style in styles:
        batch_results = generate.batch_generate(
            prompts=base_prompts,
            style=style,
            resolution="1024x1024"
        )
        print(f"Generated images in {style} style for {len(base_prompts)} prompts")

# Example usage
base_prompts = [
    "person walking on sidewalk",
    "car driving on road",
    "dog running in park"
]

augment_dataset_with_synthetic_images(base_prompts, "synthetic_dataset")

Error Handling

The generate module includes comprehensive error handling for common issues:

Invalid Prompt

Empty or inappropriate prompts will raise a ValueError

python

try:
    images = generate.synthetic_images("")
except ValueError as e:
    print(f"Error: {e}")

Generation Failure

Network or model issues will raise a GenerationError

python

try:
    images = generate.synthetic_images("a beautiful landscape")
except GenerationError as e:
    print(f"Generation failed: {e}")

Best Practices

Prompt Engineering

Be specific and descriptive in your prompts
Include details about lighting, composition, and style
Use consistent terminology across related prompts
Test prompts with small batches before large generation

Performance Optimization

Use batch_generate for multiple different prompts
Use generate_with_variations for data augmentation
Choose appropriate resolution based on your needs
Consider quality vs. speed trade-offs

Data Augmentation Strategy

Generate variations of existing training data
Create synthetic data for underrepresented classes
Use different styles to increase dataset diversity
Validate synthetic data quality before training

cvpal.generate Module

Open Source Module

Installation

Import

Functions

synthetic_images

Function Signature

Parameters

Returns

Example

batch_generate

Function Signature

Parameters

Returns

Example

generate_with_variations

Function Signature

Parameters

Returns

Example

Complete Example

Error Handling

Invalid Prompt

Generation Failure

Best Practices

Prompt Engineering

Performance Optimization

Data Augmentation Strategy

Related Documentation

Table of Contents