Crop image to aspect ratio
Cropping an image to a precise aspect ratio is easy to describe but surprisingly easy to calculate incorrectly.
Run — free
This tool accepts the source width and height plus a target ratio such as 16:9, then returns the largest rectangle with that ratio that fits inside the image. The crop is centered, so equal amounts are removed from opposite sides. Nothing is uploaded or transformed: the result is a reusable set of crop coordinates for an editor, script, image pipeline, or responsive layout.
Turn dimensions and a ratio into a crop rectangle
Start with the image's width and height in pixels, then enter the target as width to height with a colon between the two values. Common choices include 1:1 for square thumbnails, 4:3 for traditional photography, 16:9 for widescreen media, and 9:16 for vertical stories. The calculator compares the source ratio with the requested ratio to identify which dimension already fits. If the source is too wide, the full height is preserved and width is removed. If the source is too tall, the full width is preserved and height is removed. The returned x and y values locate the upper-left corner of the crop, while width and height describe its size. Together, those four values form a complete crop box. Because the calculation seeks the largest fitting rectangle, it never wastes usable image area by shrinking both dimensions. The original pixels are not resampled, stretched, or padded; the result describes only which centered region to retain.
Understand centering and fractional coordinates
A centered crop removes the same amount from both opposing edges. When a landscape image must become narrower, the x coordinate is half of the discarded width and y is zero. When a portrait or square image must become shorter, y is half of the discarded height and x is zero. Some combinations of image dimensions and ratios produce fractional coordinates or crop dimensions. That is mathematically correct: the exact center or exact ratio can fall between physical pixel boundaries. Many image libraries accept floating-point crop geometry or perform their own sampling when the operation is rendered. If your particular library requires integer coordinates, apply its documented rounding policy at the final integration point, because rounding can make the pixel rectangle differ slightly from the exact requested ratio. Keeping precise values in this result avoids silently choosing a policy on your behalf and makes repeated calculations deterministic across browser, API, and automation use.
Use the result safely in an image workflow
Treat the returned box as geometry rather than as a modified image. Pass x, y, width, and height to the crop function in your chosen graphics library, command-line tool, canvas routine, or media service. Confirm whether that destination expects an upper-left origin, because this calculator follows the common convention where x increases to the right and y increases downward. Validate the source dimensions against the actual decoded image instead of relying on a filename or metadata copied from another rendition. The ratio field must contain exactly two positive numeric parts separated by one colon; malformed text, zero values, negative values, and alternative separators are rejected rather than guessed. This strict behavior is useful in batch pipelines, where accepting an ambiguous ratio could generate hundreds of incorrect assets. The computation uses no network calls, randomness, timestamps, or hidden image analysis, so identical inputs always return identical crop geometry and can be cached or recorded in a build manifest.
What you can do with it
Prepare consistent social media assets
Calculate centered 1:1, 4:5, or 9:16 boxes before producing a set of channel-specific image variants.
Build thumbnail pipelines
Feed deterministic crop geometry into an image processor so every thumbnail fills its frame without distortion or padding.
Preview editorial crops
Show the maximum centered region for a proposed ratio before an editor decides whether a subject-aware adjustment is needed.
FAQ
Does this tool crop or upload my image?
No. It calculates crop coordinates from dimensions and a ratio. It does not receive, store, decode, or modify image data.
What does the calculation cost?
The API price is $0.002 per request. The browser version performs the same deterministic calculation locally.
Why can the result contain decimal pixel values?
An exact aspect ratio or exact center can fall between pixel boundaries. Decimal geometry preserves the mathematically largest centered crop.
What ratio syntax is accepted?
Use two positive numbers separated by a colon, such as 16:9, 4:3, 1:1, or 1.85:1. Other separators and extra text are rejected.
Will the crop ever extend outside the source image?
No. One crop dimension always equals the corresponding source dimension, and the other is reduced to fit the target ratio.
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/image/crop-to-aspect \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"width":1920,"height":1080,"ratio":"4:3"}'const res = await fetch("https://api.kit.forhosting.com/image/crop-to-aspect", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"width": 1920,
"height": 1080,
"ratio": "4:3"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/image/crop-to-aspect",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"width": 1920,
"height": 1080,
"ratio": "4:3"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/image/crop-to-aspect", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"width":1920,"height":1080,"ratio":"4:3"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"width":1920,"height":1080,"ratio":"4:3"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/image/crop-to-aspect", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"width": 1920,
"height": 1080,
"ratio": "4:3"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "image.crop_to_aspect",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
max_mb | 15 |
max_megapixels | 12 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |