Frame Image Converter — Smart Aspect Ratio Converter for Any Dimension

Transform any image to your desired aspect ratio instantly with professional-grade image processing. Convert photos, graphics, and artwork to perfect dimensions while maintaining quality and visual appeal — built as a production-ready Apify Actor with pay-per-event billing.

---

💰 Pricing — Pay Per Event

This actor uses Apify's Pay Per Event model. You are only charged for results you actually receive — no charge for failed images.

Event	Price	When
image-processed-success	$0.005 per image	Charged once per image successfully downloaded, converted, and stored

Example: Processing 100 images costs $0.50. Failed images are never charged.

This model is transparent, predictable, and fair — you pay only for value delivered. Learn more about Apify Pay Per Event.

---

✨ Key Features

• Any Aspect Ratio — Square (1:1), widescreen (16:9), portrait (4:5), vertical (9:16), ultrawide (21:9), or any custom ratio
• Smart Background Fill — White, black, transparent, blurred original, or custom hex color
• Three Resize Modes — Fit (pad), Fill (crop), Stretch
• Batch Processing — Up to 100 images per run with async concurrency control
• Output Formats — PNG, JPEG, WebP with quality control
• Cloud Storage Support — Google Drive, Dropbox, OneDrive, Box, GitHub, GitLab
• Retry Logic — Configurable exponential backoff for resilient downloads
• Memory Safe — Streaming downloads with configurable size limits (128–256 MB)

---

🚀 Quick Start

1. Go to the actor page on Apify and click Try for free
2. Paste your image URLs into Image URLs
3. Choose your Aspect Ratio, Background, and Output Format
4. Click Start — results appear in the Dataset tab

---

⚙️ Input Configuration

Parameter	Type	Default	Description
imageUrls	array	—	Required. List of image URLs (max 100). Supports direct links and cloud storage share URLs.
aspectRatio	string	1:1	Target aspect ratio preset. Options: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 4:5, 5:4, 21:9, custom
customAspectRatio	string	7:3	Custom ratio in W:H format. Only used when aspectRatio is custom.
outputSize	integer	1080	Reference dimension in pixels (100–8000). Width for landscape/square; height for portrait.
backgroundColor	string	white	Background fill: white, black, transparent, blur, custom
customColor	string	#FFFFFF	Hex color for background when backgroundColor is custom.
resizeMode	string	fit	fit — pad with background · fill — crop to fill · stretch — distort to fill
outputFormat	string	PNG	Output image format: PNG, JPEG, WEBP
jpegQuality	integer	90	Compression quality for JPEG/WEBP (1–100)
maxConcurrency	integer	5	Max simultaneous downloads/processing (1–20)
downloadTimeoutSecs	integer	60	Per-image download timeout in seconds (5–300)
maxImageSizeMb	integer	20	Max input image size in MB (1–100). Larger images are skipped.
retryPolicy	object	{maxRetries:3, backoffMultiplier:2.0, initialDelay:1.0}	Retry configuration for failed downloads
proxySettings	object	—	Optional Apify proxy configuration

---

📊 Output — Dataset Fields

Each processed image produces one dataset record:

Field	Type	Description
index	integer	Zero-based position in the input list
originalUrl	string	Source image URL
processedUrl	string	Public URL of the converted image in key-value store
filename	string	Generated filename for the output image
processedKey	string	Key-value store key for the processed image
success	boolean	true if processed successfully
aspectRatio	string	Applied aspect ratio (e.g. 16:9)
originalDimensions	object	{width, height} of the source image
finalDimensions	object	{width, height} of the output image
originalFormat	string	Detected source format (JPEG, PNG, etc.)
outputFormat	string	Output format used
originalSize	integer	Source image size in bytes
processedSize	integer	Output image size in bytes
compressionRatio	number	processedSize / originalSize
processingTime	number	Image processing time in seconds (excl. download)
totalProcessingTime	number	Total time including download in seconds
backgroundType	string	Background type applied
resizeMode	string	Resize mode used
imageHash	string	Perceptual average hash for deduplication
error	string	Error message (only present when success is false)
timestamp	string	ISO 8601 UTC timestamp

---

🎨 Aspect Ratio Presets

Ratio	Use Case
1:1	Instagram feed, profile photos, product thumbnails
4:3	Presentations, classic TV, standard photography
3:4	Portrait standard
16:9	YouTube thumbnails, HD video, website banners
9:16	Instagram Reels, TikTok, Stories
3:2	DSLR / 35mm film photography
2:3	Portrait photography
4:5	Instagram portrait posts
5:4	Large format photography
21:9	Ultrawide cinematic banners
custom	Any ratio you define (e.g. 7:3, 2.35:1)

---

🌐 Supported Cloud Storage

Platform	Supported URL Format
Google Drive	/file/d/FILE_ID/view share links
Dropbox	dropbox.com/s/… share links
OneDrive	onedrive.live.com and 1drv.ms links
Box	box.com/s/… share links
GitHub	/blob/ URLs (auto-converted to raw)
GitLab	/blob/ URLs (auto-converted to raw)
Direct URLs	Any publicly accessible image URL

---

🔧 Background Modes

Mode	Description
white	Clean white background (default)
black	Solid black background
transparent	Transparent fill — PNG output only
blur	Blurred version of the original image as background (artistic effect)
custom	Any hex color (e.g. #FF5733)

---

📐 Resize Modes

Mode	Behaviour
fit	Scales image to fit within the target frame; pads remaining space with background
fill	Crops the image to fill the entire target frame (center crop)
stretch	Stretches/distorts the image to exactly fill the target dimensions

---

🏗️ Technical Architecture

• Runtime: Python 3.12 on apify/actor-python:3.12
• Image Engine: Pillow (PIL) with LANCZOS resampling for maximum quality
• HTTP Client: aiohttp with streaming downloads, DNS caching, and connection pooling
• Concurrency: asyncio + asyncio-throttle for controlled parallel processing
• Retry: Custom exponential backoff (configurable retries, multiplier, initial delay)
• Memory: Streaming chunk-based download with configurable size guard
• Billing: Apify Pay Per Event — Actor.charge() called only on successful image processing
• Memory Limits: 128 MB minimum, 256 MB maximum

---

📁 Project Structure

frame-image-converter/
├── .actor/
│   ├── actor.json          # Actor definition (memory limits, schema refs)
│   ├── input_schema.json   # Input schema with defaults & prefills
│   ├── dataset_schema.json # Dataset view & column definitions
│   ├── output_schema.json  # Output record schema
│   └── pay_per_event.json  # PPE event definitions
├── src/
│   └── main.py             # Actor entry point & processing logic
├── Dockerfile              # Container definition
├── requirements.txt        # Python dependencies
└── README.md

---

❓ FAQ

Why Pay Per Event instead of compute-based pricing? PPE is fairer and more predictable. You pay $0.005 per successfully converted image — no charge for failures, no surprise bills from idle compute time.

What happens if an image fails to download? The actor retries up to 3 times (configurable) with exponential backoff. If all retries fail, the failure is recorded in the dataset with an error message and no charge is applied.

Can I process images from private cloud storage? Cloud storage URLs must be publicly accessible share links. Private files require you to generate a public share link first.

What is the maximum image size? Default is 20 MB per image (configurable up to 100 MB). Images exceeding the limit are skipped with an error record.

Does transparent background work with JPEG? No — JPEG does not support transparency. Use PNG or WEBP output format when selecting the transparent background option.

How do I get the processed images? Each dataset record contains a processedUrl field — a direct public link to the converted image stored in the actor's key-value store.