Media Assets¶

The Konigle SDK provides comprehensive support for managing media assets including images, videos, and documents. All media asset operations support both synchronous and asynchronous clients with consistent APIs.

Images¶

The Image manager provides full CRUD operations for image assets with support for multiple file input formats.

Creating Images¶

The SDK supports various ways to create images:

From File Path¶

import konigle
from konigle.models.core.media_asset import ImageCreate

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

# Create an image from a file path
image_data = ImageCreate(
    name="product-hero",
    alt_text="Hero image for product page",
    tags="product,hero,main",
    image="/path/to/image.jpg"
    description="High-resolution hero image for the main product page"
)

image = client.images.create(image_data)
print(f"Created image: {image.id}")
print(f"Asset URL: {image.asset_url}")

Adding description to the image will allow Konigle AI to use the right image for relevant use-cases.

From Bytes¶

# Read image as bytes
with open("/path/to/image.jpg", "rb") as f:
    image_bytes = f.read()

image_data = ImageCreate(
    name="profile-avatar",
    alt_text="User profile avatar",
    tags="user,profile,avatar",
    image=image_bytes
)

image = client.images.create(image_data)

From BytesIO¶

import io
from PIL import Image as PILImage

# Create image from BytesIO (useful for generated images)
pil_image = PILImage.new('RGB', (100, 100), color='red')
image_buffer = io.BytesIO()
pil_image.save(image_buffer, format='JPEG')
image_buffer.seek(0)

image_data = ImageCreate(
    name="generated-thumbnail",
    alt_text="Auto-generated thumbnail",
    tags="generated,thumbnail",
    image=(image_buffer, "thumbnail.jpg")  # Tuple with filename
)

image = client.images.create(image_data)

Minimal Example¶

# Minimal required fields
image_data = ImageCreate(
    name="simple-image",
    image="/path/to/image.png"
)

image = client.images.create(image_data)

Generating Images from Text¶

The SDK supports AI-powered image generation from text prompts.

from konigle.models.core import ImageGenerate

# Generate an image from a text prompt
image_gen = ImageGenerate(
    prompt="A serene mountain landscape at sunset with snow-capped peaks",
    aspect_ratio="16:9",
    output_format="webp"
)

generated_image = client.images.generate(image_gen)
print(f"Generated image: {generated_image.id}")
print(f"Asset URL: {generated_image.asset_url}")

# Minimal example with defaults (1:1 aspect ratio, webp format)
image_gen = ImageGenerate(
    prompt="A futuristic city with flying cars"
)

generated_image = client.images.generate(image_gen)

Supported aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9

Supported output formats: webp, png, jpg, jpeg

Using the CLI¶

# Generate an image with default settings (1:1, webp)
konigle images generate --prompt "A beautiful sunset over mountains"

# Specify aspect ratio and output format
konigle images generate \
  --prompt "A cat in space wearing an astronaut suit" \
  --aspect-ratio "16:9" \
  --output-format "png"

# Short form options
konigle images generate -p "Abstract geometric art" -r "3:4" -f "jpg"

Async Image Generation¶

async def generate_image():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        image_gen = ImageGenerate(
            prompt="A peaceful zen garden with cherry blossoms",
            aspect_ratio="4:3",
            output_format="png"
        )

        generated_image = await client.images.generate(image_gen)
        print(f"Generated: {generated_image.asset_url}")

asyncio.run(generate_image())

Searching Images¶

The SDK provides full-text search functionality to find images by text query.

# Search for images by text query
search_results = client.images.search(
    query="mountain sunset",
    page=1,
    page_size=10
)

print(f"Found {search_results.count} images")
for image in search_results.payload:
    print(f"- {image.name}")
    print(f"  Alt text: {image.alt_text}")
    print(f"  URL: {image.asset_url}")

# Search with pagination
page_2_results = client.images.search(
    query="product hero",
    page=2,
    page_size=20
)

Using the CLI¶

# Search for images
konigle images search --query "mountain landscape"

# Search with pagination
konigle images search --query "product" --page 2 --page-size 20

# Short form options
konigle images search -q "sunset" -p 1 -s 10

Async Image Search¶

async def search_images():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        results = await client.images.search(
            query="nature photography",
            page=1,
            page_size=15
        )

        print(f"Found {results.count} matching images")
        for image in results.payload:
            print(f"- {image.name}: {image.asset_url}")

asyncio.run(search_images())

Listing Images¶

# List all images with pagination
images = client.images.list(page=1, page_size=20)

print(f"Total images: {images.count}")
print(f"Current page: {images.current_page}")
print(f"Total pages: {images.num_pages}")

for image in images.payload:
    print(f"- {image.name} ({image.id})")
    print(f"  Size: {image.size} bytes")
    print(f"  Dimensions: {image.image_width}x{image.image_height}")
    print(f"  URL: {image.asset_url}")

# Check if there are more pages
if images.has_next():
    next_page = client.images.list(page=2, page_size=20)

Filtering Images¶

from konigle.filters.core import ImageFilters

# Using filter object (type-safe)
image_filters = ImageFilters(
    q="product",  # Search in name and alt_text
    min_size=1000,  # Minimum 1KB
    max_size=5000000,  # Maximum 5MB
    tags="hero,main"  # Images with hero OR main tags
)

filtered_images = client.images.list(
    page=1,
    page_size=10,
    filters=image_filters
)

# Using filter kwargs (more concise)
filtered_images = client.images.list(
    q="avatar",
    min_size=500,
    max_size=100000,
    tags="user,profile"
)

# Search by text query
search_results = client.images.list(q="hero image")

# Filter by size range
large_images = client.images.list(min_size=1000000)  # > 1MB

# Filter by tags
tagged_images = client.images.list(tags="product,catalog")

Getting a Specific Image¶

# Get image by ID
image = client.images.get("img_123456789")
print(f"Image: {image.name}")
print(f"Alt text: {image.alt_text}")
print(f"Tags: {image.tags}")

Updating Images¶

from konigle.models.core.media_asset import ImageUpdate

# Update image metadata (file cannot be updated)
update_data = ImageUpdate(
    name="updated-product-hero",
    alt_text="Updated hero image for product page",
    tags="product,hero,main,updated"
)

updated_image = client.images.update("img_123456789", update_data)
print(f"Updated image: {updated_image.name}")

Deleting Images¶

# Delete an image
success = client.images.delete("img_123456789")
if success:
    print("Image deleted successfully")
else:
    print("Failed to delete image")

Iterating All Images¶

# Memory-efficient iteration over all images
for image in client.images.iter_all(page_size=50):
    print(f"Processing image: {image.name}")
    # Process each image...

# With filtering
for image in client.images.iter_all(page_size=50, tags="product"):
    print(f"Processing product image: {image.name}")

Async Operations¶

import asyncio
import konigle

async def manage_images():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create image
        image_data = ImageCreate(
            name="async-image",
            alt_text="Image created asynchronously",
            image="/path/to/image.jpg"
        )
        image = await client.images.create(image_data)

        # List images with filtering
        images = await client.images.list(
            page_size=10,
            q="product",
            tags="hero"
        )

        # Update image
        update_data = ImageUpdate(name="updated-async-image")
        updated_image = await client.images.update(image.id, update_data)

        # Delete image
        await client.images.delete(image.id)

asyncio.run(manage_images())

Supported Image Formats¶

The SDK supports the following image formats:

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
WebP (.webp)

Error Handling¶

from konigle.exceptions import ValidationError

try:
    # This will raise a validation error
    invalid_image = ImageCreate(
        name="invalid-file",
        image="document.pdf"  # Invalid format
    )
except ValueError as e:
    print(f"Validation error: {e}")

try:
    image = client.images.create(image_data)
except ValidationError as e:
    print(f"API validation error: {e}")
except Exception as e:
    print(f"Network or other error: {e}")

Videos¶

The Video manager provides the same CRUD operations as images but handles video file formats.

Creating Videos¶

from konigle.models.core.media_asset import VideoCreate

# Create video from file path
video_data = VideoCreate(
    name="product-demo",
    alt_text="Product demonstration video",
    tags="product,demo,tutorial",
    file="/path/to/video.mp4"
)

video = client.videos.create(video_data)
print(f"Created video: {video.id}")

Searching Videos¶

The SDK provides full-text search functionality to find videos by text query.

# Search for videos by text query
search_results = client.videos.search(
    query="product demo",
    page=1,
    page_size=10
)

print(f"Found {search_results.count} videos")
for video in search_results.payload:
    print(f"- {video.name}")
    print(f"  Alt text: {video.alt_text}")
    print(f"  URL: {video.asset_url}")

# Search with pagination
page_2_results = client.videos.search(
    query="tutorial",
    page=2,
    page_size=20
)

Async Video Search¶

async def search_videos():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        results = await client.videos.search(
            query="marketing campaign",
            page=1,
            page_size=15
        )

        print(f"Found {results.count} matching videos")
        for video in results.payload:
            print(f"- {video.name}: {video.asset_url}")

asyncio.run(search_videos())

Filtering Videos¶

from konigle.filters.core import VideoFilters

# Using filter object
video_filters = VideoFilters(
    q="tutorial",
    min_size=10000000,  # Videos larger than 10MB
    tags="demo,tutorial"
)

filtered_videos = client.videos.list(filters=video_filters)

# Using filter kwargs
large_videos = client.videos.list(
    min_size=50000000,  # > 50MB
    q="marketing"
)

Complete Video Management Example¶

import konigle
from konigle.models.core.media_asset import VideoCreate, VideoUpdate

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

# Create video
video_data = VideoCreate(
    name="marketing-video",
    alt_text="Marketing campaign video",
    tags="marketing,campaign,2024",
    file="/path/to/marketing.mp4"
)

video = client.videos.create(video_data)

# List videos with filtering
videos = client.videos.list(
    page_size=10,
    tags="marketing"
)
print(f"Found {videos.count} marketing videos")

# Update video metadata
update_data = VideoUpdate(
    name="updated-marketing-video",
    alt_text="Updated marketing campaign video"
)
updated_video = client.videos.update(video.id, update_data)

# Get specific video
retrieved_video = client.videos.get(video.id)

# Delete video
client.videos.delete(video.id)

Supported Video Formats¶

MP4 (.mp4)
WebM (.webm)

Async Video Operations¶

async def manage_videos():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        video_data = VideoCreate(
            name="async-video",
            file="/path/to/video.mp4"
        )

        video = await client.videos.create(video_data)

        # List with filtering
        videos = await client.videos.list(
            q="demo",
            min_size=1000000
        )

        await client.videos.delete(video.id)

asyncio.run(manage_videos())

Documents¶

The Document manager handles various document formats with the same API pattern.

Creating Documents¶

from konigle.models.core.media_asset import DocumentCreate

# Create document from file path
doc_data = DocumentCreate(
    name="user-manual",
    alt_text="Product user manual",
    tags="manual,documentation,help",
    file="/path/to/manual.pdf"
)

document = client.documents.create(doc_data)
print(f"Created document: {document.id}")

Searching Documents¶

The SDK provides full-text search functionality to find documents by text query.

# Search for documents by text query
search_results = client.documents.search(
    query="user manual",
    page=1,
    page_size=10
)

print(f"Found {search_results.count} documents")
for document in search_results.payload:
    print(f"- {document.name}")
    print(f"  Alt text: {document.alt_text}")
    print(f"  URL: {document.asset_url}")

# Search with pagination
page_2_results = client.documents.search(
    query="quarterly report",
    page=2,
    page_size=20
)

Async Document Search¶

async def search_documents():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        results = await client.documents.search(
            query="technical documentation",
            page=1,
            page_size=15
        )

        print(f"Found {results.count} matching documents")
        for document in results.payload:
            print(f"- {document.name}: {document.asset_url}")

asyncio.run(search_documents())

Filtering Documents¶

from konigle.filters.core import DocumentFilters

# Using filter object
doc_filters = DocumentFilters(
    q="report",
    max_size=10000000,  # Documents smaller than 10MB
    tags="quarterly,finance"
)

filtered_docs = client.documents.list(filters=doc_filters)

# Using filter kwargs
pdf_docs = client.documents.list(
    q="manual",
    tags="documentation"
)

Complete Document Management Example¶

import konigle
from konigle.models.core.media_asset import DocumentCreate, DocumentUpdate

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

# Create document from bytes
with open("/path/to/report.pdf", "rb") as f:
    doc_bytes = f.read()

doc_data = DocumentCreate(
    name="quarterly-report",
    alt_text="Q4 2024 quarterly report",
    tags="report,quarterly,2024,finance",
    file=doc_bytes
)

document = client.documents.create(doc_data)

# List documents with filtering
documents = client.documents.list(
    page_size=25,
    tags="report,finance",
    q="quarterly"
)

# Update document metadata
update_data = DocumentUpdate(
    name="q4-2024-report",
    tags="report,quarterly,2024,finance,final"
)
updated_doc = client.documents.update(document.id, update_data)

# Iterate all documents with filtering
for doc in client.documents.iter_all(tags="documentation"):
    print(f"Document: {doc.name} - {doc.size} bytes")

# Delete document
client.documents.delete(document.id)

Supported Document Formats¶

PDF (.pdf)
CSV (.csv)
Text files (.txt)
Microsoft Word (.docx, .doc)
Microsoft Excel (.xlsx, .xls)

Async Document Operations¶

async def manage_documents():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        doc_data = DocumentCreate(
            name="async-document",
            file="/path/to/document.pdf"
        )

        document = await client.documents.create(doc_data)

        # List with filtering
        documents = await client.documents.list(
            tags="manual",
            q="user guide"
        )

        # Async iteration with filtering
        async for doc in client.documents.iter_all(min_size=1000):
            print(f"Processing: {doc.name}")

        await client.documents.delete(document.id)

asyncio.run(manage_documents())

Common Patterns¶

Context Manager Usage¶

# Recommended pattern for resource management
with konigle.Client(api_key="your-api-key") as client:
    image = client.images.create(image_data)
    # Client automatically closed when exiting context

# Async version
async with konigle.AsyncClient(api_key="your-api-key") as client:
    image = await client.images.create(image_data)
    # Client automatically closed when exiting context

Batch Operations¶

# Process multiple files
image_files = [
    "/path/to/image1.jpg",
    "/path/to/image2.png",
    "/path/to/image3.gif"
]

created_images = []

with konigle.Client(api_key="your-api-key") as client:
    for i, file_path in enumerate(image_files):
        image_data = ImageCreate(
            name=f"batch-image-{i+1}",
            tags="batch,upload",
            image=file_path
        )
        image = client.images.create(image_data)
        created_images.append(image)

print(f"Created {len(created_images)} images")

# Find all batch uploaded images
batch_images = client.images.list(tags="batch")

Error Handling Best Practices¶

import konigle
from konigle.exceptions import ValidationError

def upload_image_safely(file_path: str) -> bool:
    try:
        with konigle.Client(api_key="your-api-key") as client:
            image_data = ImageCreate(
                name="safe-upload",
                image=file_path
            )
            image = client.images.create(image_data)
            print(f"Successfully uploaded: {image.id}")
            return True

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

success = upload_image_safely("/path/to/image.jpg")