Overview
The Imagen AI SDK provides a complete workflow for automated photo editing. The process follows a clear sequence of steps that transform your raw images into professionally edited photos ready for client delivery.Workflow Steps
The complete workflow consists of six main steps:Create a Project
Projects are containers for organizing related images and edits. Each project can contain either RAW files or JPEG files, but not both types mixed together.
Project names must be unique across your account. If a project with the same name already exists, the method will raise a
ProjectError. Consider using timestamps or client identifiers in project names to ensure uniqueness.Upload Images
Upload your images to the project with concurrent processing and optional progress tracking. The SDK handles presigned URLs, S3 uploads, and integrity verification automatically.The upload process:
- Validates local file paths
- Requests presigned S3 URLs from the API
- Uploads files concurrently to cloud storage
- Returns an
UploadSummarywith statistics
Start Editing
Initiate AI-powered editing using your trained profile. The SDK automatically polls the status until editing completes.This method blocks until editing completes (can take several minutes). Progress is logged automatically during the process.
Get Download Links
Retrieve temporary download URLs for the generated XMP edit files. These XMP files contain Lightroom-compatible edit instructions.
Export to JPEG (Optional)
Convert the AI-edited images to final JPEG files for client delivery. This step is optional but recommended for final output.The export process applies all edits and generates high-quality JPEG files ready for delivery.
Complete Example
Here’s a complete workflow example showing all steps together:Quick Workflow Function
For simpler use cases, the SDK provides aquick_edit() convenience function that handles the entire workflow in one call:
quick_edit() function automatically:
- Creates a project
- Validates file types
- Uploads images
- Starts editing
- Gets download links
- Optionally exports to JPEG
- Optionally downloads files
What You Receive
The Imagen AI SDK returns Adobe-compatible edit instructions (XMP files) that preserve your original files and allow for non-destructive editing.XMP Files (Edit Instructions)
- Format: Adobe XMP sidecar files
- Compatible with: Lightroom Classic, Lightroom, Photoshop, Bridge
- Usage: Open in your Adobe application to see AI-applied edits
- Editable: Further adjust the AI-generated edits as needed
- Non-destructive: Original RAW files remain untouched
JPEG Files (Optional Export)
- Format: High-quality JPEG images
- Use case: Final client delivery
- Content: All AI edits applied and rendered
- Ready for: Direct delivery, web upload, printing
Resource Management
The SDK uses an async context manager for automatic session cleanup:Error Handling
Each step in the workflow can raise specific exceptions:Status Polling
The SDK automatically handles status polling for long-running operations:- Initial interval: 10 seconds
- Max interval: 60 seconds (with exponential backoff)
- Max wait time: 20 hours
- Auto-retry: Built-in with increasing intervals
start_editing() and export_project() methods handle this automatically.
Best Practices
Use Context Managers
Always use
async with to ensure proper session cleanupTrack Progress
Use progress callbacks for long-running uploads and downloads
Enable MD5 Verification
Set
calculate_md5=True for critical uploads to ensure integrityHandle Errors
Implement proper error handling for each workflow step
Next Steps
Profiles
Learn about AI profiles and how to use them
Edit Options
Explore all available editing parameters
File Formats
See supported RAW and JPEG formats
API Reference
View detailed API documentation