Product Images

Product images are essential for showcasing your products to customers. The Konigle SDK provides comprehensive support for managing product images including uploading, organizing, associating with variants, setting cover images, and managing image metadata.

Adding New Images

Basic Image Upload

Upload images to a product using various input methods:

import konigle
from konigle.models.commerce.product_image import ProductImageCreate

client = konigle.Client(api_key="your-api-key")

# Upload image from file path
image_data = ProductImageCreate(
    product="prod_123456789",  # Product ID
    file="/path/to/product-image.jpg",
    alt="Premium T-Shirt Front View",
    position=1
)

image = client.product_images.create(image_data)
print(f"Created image: {image.id}")
print(f"Image URL: {image.url}")
print(f"Position: {image.position}")

Upload from Bytes

# Upload image from bytes data
with open("/path/to/product-image.jpg", "rb") as f:
    image_bytes = f.read()

image_data = ProductImageCreate(
    product="prod_123456789",
    file=image_bytes,
    alt="Product image uploaded from bytes",
    position=2
)

image = client.product_images.create(image_data)

Upload from BytesIO

import io
from PIL import Image as PILImage

# Create image from BytesIO (useful for processed images)
pil_image = PILImage.open("/path/to/original.jpg")
pil_image = pil_image.resize((800, 600))  # Process the image

image_buffer = io.BytesIO()
pil_image.save(image_buffer, format='JPEG', quality=85)
image_buffer.seek(0)

image_data = ProductImageCreate(
    product="prod_123456789",
    file=(image_buffer, "processed-image.jpg"),  # Tuple with filename
    alt="Processed product image",
    position=3
)

image = client.product_images.create(image_data)

Multiple Image Upload

# Upload multiple images to a product
product_id = "prod_123456789"
image_files = [
    "/path/to/front-view.jpg",
    "/path/to/back-view.jpg",
    "/path/to/side-view.jpg",
    "/path/to/detail-shot.jpg"
]

created_images = []

with konigle.Client(api_key="your-api-key") as client:
    for i, file_path in enumerate(image_files, 1):
        image_data = ProductImageCreate(
            product=product_id,
            file=file_path,
            alt=f"Product view {i}",
            position=i
        )
        image = client.product_images.create(image_data)
        created_images.append(image)
        print(f"Uploaded image {i}: {image.id}")

print(f"Successfully uploaded {len(created_images)} images")

Setting Cover Images

Product Cover Image

Set the main cover image for the entire product:

from konigle.models.commerce.product import ProductUpdate

# First, create or get an image
image_data = ProductImageCreate(
    product="prod_123456789",
    file="/path/to/hero-image.jpg",
    alt="Product hero image",
    position=1
)
hero_image = client.product_images.create(image_data)

# Set as product cover image
product_update = ProductUpdate(
    image=hero_image.id  # Set the image ID as product cover
)

updated_product = client.products.update("prod_123456789", product_update)
print(f"Set cover image for product: {updated_product.title}")

Variant Cover Image

Set a specific image as the cover for a product variant:

from konigle.models.commerce.product_variant import ProductVariantUpdate

# Create variant-specific image
variant_image_data = ProductImageCreate(
    product="prod_123456789",
    file="/path/to/red-variant.jpg",
    alt="Red variant of product",
    variant_ids=["variant_987654321"]  # Associate with specific variant
)
variant_image = client.product_images.create(variant_image_data)

# Set as variant cover image
variant_update = ProductVariantUpdate(
    image=variant_image.id  # Set the image ID as variant cover
)

updated_variant = client.product_variants.update("variant_987654321", variant_update)
print(f"Set cover image for variant: {updated_variant.title}")

Associating Images with Variants

Single Variant Association

# Create image and associate with specific variant
image_data = ProductImageCreate(
    product="prod_123456789",
    file="/path/to/blue-variant.jpg",
    alt="Blue color variant",
    variant_ids=["variant_blue_123"]  # Associate with one variant
)

image = client.product_images.create(image_data)
print(f"Image associated with variant: {image.variant_ids}")

Multiple Variant Association

# Associate one image with multiple variants
image_data = ProductImageCreate(
    product="prod_123456789",
    file="/path/to/shared-detail.jpg",
    alt="Detail shot shared across variants",
    variant_ids=[
        "variant_small_red",
        "variant_medium_red",
        "variant_large_red"
    ]  # Associate with multiple variants
)

image = client.product_images.create(image_data)
print(f"Image associated with {len(image.variant_ids)} variants")

Update Variant Associations

from konigle.models.commerce.product_image import ProductImageUpdate

# Update existing image to associate with different variants
image_update = ProductImageUpdate(
    variant_ids=[
        "variant_new_1",
        "variant_new_2",
        "variant_new_3"
    ]
)

updated_image = client.product_images.update("img_123456789", image_update)
print(f"Updated variant associations: {updated_image.variant_ids}")

# Remove all variant associations (make it a general product image)
image_update = ProductImageUpdate(variant_ids=[])
general_image = client.product_images.update("img_123456789", image_update)

Organizing Images

Setting Image Position

from konigle.models.commerce.product_image import ProductImageUpdate

# Reorder images by updating positions
image_updates = [
    ("img_first", 1),   # Move to first position
    ("img_second", 2),  # Move to second position
    ("img_third", 3),   # Move to third position
]

for image_id, new_position in image_updates:
    update_data = ProductImageUpdate(position=new_position)
    updated_image = client.product_images.update(image_id, update_data)
    print(f"Updated {image_id} to position {new_position}")

Updating Alt Text

# Update alt text for accessibility
image_update = ProductImageUpdate(
    alt="Premium cotton t-shirt in navy blue - front view with model"
)

updated_image = client.product_images.update("img_123456789", image_update)
print(f"Updated alt text: {updated_image.alt}")

Listing and Filtering Images

List All Product Images

from konigle.filters.commerce import ProductImageFilters

# List all images for a specific product
product_filters = ProductImageFilters(
    product_id="prod_123456789",
    ordering="position"  # Order by position
)

product_images = client.product_images.list(filters=product_filters)

print(f"Found {product_images.count} images for product")
for image in product_images.payload:
    print(f"- Position {image.position}: {image.alt}")
    print(f"  Variants: {image.variant_ids}")
    print(f"  URL: {image.url}")

Filter by Ordering

# Get images ordered by creation date (newest first)
recent_filters = ProductImageFilters(
    product_id="prod_123456789",
    ordering="-created_at"
)

recent_images = client.product_images.list(filters=recent_filters)

# Get images ordered by position (display order)
position_filters = ProductImageFilters(
    product_id="prod_123456789",
    ordering="position"
)

ordered_images = client.product_images.list(filters=position_filters)

Get Specific Image

# Get detailed information about a specific image
image = client.product_images.get("img_123456789")

print(f"Image: {image.id}")
print(f"Product: {image.product}")
print(f"Position: {image.position}")
print(f"Dimensions: {image.width}x{image.height}")
print(f"Alt text: {image.alt}")
print(f"Associated variants: {image.variant_ids}")
print(f"URL: {image.url}")

Deleting Images

Delete Single Image

# Delete a specific product image
try:
    success = client.product_images.delete("img_123456789")
    if success:
        print("Image deleted successfully")
    else:
        print("Failed to delete image")
except Exception as e:
    print(f"Error deleting image: {e}")

Bulk Delete Images

# Delete multiple images for a product
product_filters = ProductImageFilters(
    product_id="prod_123456789",
    ordering="position"
)

# Get all images for the product
images = client.product_images.list(filters=product_filters)

# Delete images beyond position 3 (keep only first 3)
for image in images.payload:
    if image.position > 3:
        try:
            client.product_images.delete(image.id)
            print(f"Deleted image at position {image.position}")
        except Exception as e:
            print(f"Failed to delete image {image.id}: {e}")

Async Operations

All product image operations support async usage:

import asyncio
import konigle

async def manage_product_images():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create image asynchronously
        image_data = ProductImageCreate(
            product="prod_123456789",
            file="/path/to/async-image.jpg",
            alt="Async uploaded product image"
        )

        image = await client.product_images.create(image_data)
        print(f"Created async image: {image.id}")

        # Update image asynchronously
        update_data = ProductImageUpdate(
            alt="Updated async image description",
            position=1
        )

        updated_image = await client.product_images.update(image.id, update_data)
        print(f"Updated image: {updated_image.alt}")

        # List images asynchronously
        filters = ProductImageFilters(product_id="prod_123456789")
        images = await client.product_images.list(filters=filters)

        print(f"Found {images.count} total images")

        # Delete image asynchronously
        await client.product_images.delete(image.id)
        print("Image deleted successfully")

# Run async function
asyncio.run(manage_product_images())

Error Handling

from konigle.exceptions import ValidationError

def upload_image_safely(product_id: str, file_path: str) -> bool:
    """Upload product image with comprehensive error handling."""
    try:
        with konigle.Client(api_key="your-api-key") as client:
            image_data = ProductImageCreate(
                product=product_id,
                file=file_path,
                alt="Product image"
            )

            image = client.product_images.create(image_data)
            print(f"Successfully uploaded image: {image.id}")
            return True

    except ValidationError as e:
        print(f"Validation error: {e}")
        return False
    except FileNotFoundError:
        print(f"Image file not found: {file_path}")
        return False
    except Exception as e:
        print(f"Unexpected error: {e}")
        return False

# Usage
success = upload_image_safely("prod_123456789", "/path/to/image.jpg")

Product images are essential for e-commerce success. Proper organization, variant associations, and cover image selection help create an engaging shopping experience for your customers.