Change image aspect ratio

Frame Image Converter is an Apify Actor that converts any image to your target aspect ratio with professional-grade processing — smart background fill, three resize modes, and PNG/JPEG/WebP output. Point it at a direct image URL or a cloud storage link (Google Drive, Dropbox, OneDrive, GitHub) and get a perfectly framed image back, charged at $0.005 per successfully converted image.

What Is Frame Image Converter?

Frame Image Converter is a cloud-based aspect ratio conversion API built on Python 3.12 with Pillow. It resizes any image to a target aspect ratio while maintaining quality and visual appeal: choose how the image fills the frame (fit/pad, fill/crop, or stretch) and what fills the leftover space (white, black, transparent, or a blurred version of the original). Every conversion returns full metadata — dimensions, formats, sizes, compression ratio, and processing time.

Key Features

• 7 aspect ratio presets — 1:1, 4:3, 3:4, 16:9, 9:16, 4:5, 21:9
• Smart Background Fill — white, black, transparent (PNG only), or blurred original
• Three Resize Modes — Fit (pad), Fill (crop), Stretch
• Output Formats — PNG, JPEG, WEBP
• Cloud Storage Support — Google Drive, Dropbox, OneDrive, GitHub links, plus any direct URL
• Quality Processing — Pillow with LANCZOS resampling for maximum quality
• Resilient Downloads — configurable retry logic with exponential backoff
• Transparent Billing — pay-per-event; no charge for failed images

Supported Image Sources

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
GitHub	/blob/ URLs (auto-converted to raw)
Direct URLs	Any publicly accessible image URL

Use Cases

• Social media — square posts (1:1), portrait posts (4:5), Reels/TikTok frames (9:16)
• Video & web — YouTube thumbnails and banners (16:9), ultrawide cinematic banners (21:9)
• Photography — standard (4:3) and portrait (3:4) framing for print and portfolios
• Product imagery — normalize marketplace images to one consistent ratio
• Automation pipelines — normalize user-uploaded images via the Apify API

Input Parameters

Parameter	Type	Required	Default	Description
imageUrl	string	Yes	—	URL of the image to process (direct links or cloud storage URLs)
aspectRatio	string	No	1:1	Target ratio: 1:1, 4:3, 3:4, 16:9, 9:16, 4:5, 21:9
backgroundColor	string	No	white	Background fill for fit mode: white, black, blur, transparent (PNG only)
resizeMode	string	No	fit	fit (pad with background), fill (crop to fill), stretch (distort to fill)
outputFormat	string	No	PNG	PNG (lossless, supports transparency), JPEG (smallest), WEBP (best compression)

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
4:5	Instagram portrait posts
21:9	Ultrawide cinematic banners

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)

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

Example input:

{
  "imageUrl": "https://example.com/photo.jpg",
  "aspectRatio": "16:9",
  "backgroundColor": "white",
  "resizeMode": "fit",
  "outputFormat": "PNG"
}

Sample Output

{
  "index": 0,
  "originalUrl": "https://example.com/photo.jpg",
  "processedUrl": "https://api.apify.com/v2/key-value-stores/.../photo.png",
  "filename": "photo.png",
  "processedKey": "processed-photo.png",
  "success": true,
  "aspectRatio": "16:9",
  "originalDimensions": { "width": 800, "height": 600 },
  "finalDimensions": { "width": 1066, "height": 600 },
  "originalFormat": "JPEG",
  "outputFormat": "PNG",
  "compressionRatio": 1.4,
  "processingTime": 0.4,
  "totalProcessingTime": 1.2,
  "backgroundType": "white",
  "resizeMode": "fit",
  "timestamp": "2026-05-18T12:00:00.000Z"
}

Each processed image produces one dataset record with the source and output dimensions, formats, file sizes, compression ratio, timing, background type, and resize mode used. Converted image files are stored in the key-value store; processedUrl is the direct public link.

How to Use the Frame Image Converter

1. Open the Actor page on Apify Store and click Start Actor.
2. Paste your image URL into imageUrl (direct link or Google Drive/Dropbox/OneDrive/GitHub share URL).
3. Choose your Aspect Ratio, Background, Resize Mode, and Output Format.
4. Click Start — grab processedUrl from the Dataset tab when the run finishes.

Connect via API

cURL:

curl -X POST "https://api.apify.com/v2/acts/akash9078/frame-image-converter/runs" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"imageUrl":"https://example.com/photo.jpg","aspectRatio":"16:9","resizeMode":"fit","outputFormat":"PNG"}'

Python:

import requests

response = requests.post(
    "https://api.apify.com/v2/acts/akash9078/frame-image-converter/runs",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={"imageUrl": "https://example.com/photo.jpg", "aspectRatio": "16:9", "resizeMode": "fit", "outputFormat": "PNG"},
)
print(response.json())

Node.js with the Apify Client:

const { ApifyClient } = require('apify-client');

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('akash9078/frame-image-converter').call({
    imageUrl: 'https://example.com/photo.jpg',
    aspectRatio: '16:9',
    resizeMode: 'fit',
    outputFormat: 'PNG',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Frame Image Converter Pricing

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.

Why Use This Instead of Manual Cropping?

Capability	Frame Image Converter	Manual editing
Aspect presets	7 ratios, one click each	Manual canvas setup
Smart fill	Blur/transparent/white/black padding	Manual masking
Cloud links	Drive/Dropbox/OneDrive/GitHub auto-handled	Manual download
Metadata	Dimensions, sizes, compression ratio per image	None
API & automation	Runs, schedules, webhooks	Not available

Limitations

• Processes one image per run (single imageUrl input)
• Aspect ratio is limited to the 7 supported presets
• Transparent background requires PNG output — JPEG does not support transparency
• Cloud storage URLs must be publicly accessible share links; private files need a public share link first
• Memory: 128 MB minimum, 256 MB maximum

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-based controlled processing
• Retry: Custom exponential backoff for resilient downloads
• Billing: Apify Pay Per Event — charged only on successful image processing

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 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.

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.

What is the maximum image size?

Downloads are streamed with a configurable size guard within the 128-256 MB memory limits; oversized sources are the most common cause of skipped images.

Related Actors

If you need more image conversion tools from Apify, check out my other Apify Actors:

• Image Format Converter
• Image and PDF Converter
• AI Background Remover - HD & Transparent
• AI Image Upscaler & Face Enhancer
• Analyze Image

---

Built and maintained by akash9078 on the Apify platform.