Optimize Image

Compress, resize, and convert images between PNG, JPEG, and WebP. Auto mode tries all formats and picks the smallest.

POST /api/optimize-image (Multipart)

Upload an image as a multipart form with optional optimization settings.

Parameters

Field	Type	Required	Description
file	file	Yes	Image file to optimize (up to 10 MB)
options	JSON string	No	Optimization options as a JSON-encoded string in the form field

Heads up: The options field is a single JSON string, not separate form fields per option. Serialize your options object to JSON and pass the whole thing as one form value. See the multipart example below.

The options JSON string accepts the same fields as the JSON route: output_format, quality, max_width, strip_metadata, and inline.

---

POST /api/optimize-image/json (JSON)

Send a base64-encoded image in a JSON body for when you already have the image in memory.

Parameters

Field	Type	Required	Default	Description
content	string	Yes	—	Base64-encoded image
output_format	string	No	auto	auto, png, jpeg, webp
quality	integer	No	85	Compression quality (1—100)
max_width	integer	No	0	Max width in pixels. 0 = no resize. Aspect ratio preserved
strip_metadata	boolean	No	false	Remove EXIF and other metadata
inline	boolean	No	false	Return base64 content instead of a presigned URL

---

Response

Both routes return the same shape.

Field	Type	Description
url	string	Presigned download URL (when inline is false)
content	string	Base64-encoded optimized image (when inline is true)
expires_at	string	URL expiry timestamp (when url is present)
original_size	integer	Original file size in bytes
optimized_size	integer	Optimized file size in bytes
reduction_percent	number	Size reduction as a percentage
output_format	string	Format of the optimized image
width	integer	Output width in pixels
height	integer	Output height in pixels

---

Auto mode

When output_format is auto (the default), the service compresses your image as PNG, JPEG, and WebP, then returns whichever produces the smallest file. You get the best compression without guessing which format suits a given image.

Inline vs URL

By default, optimized images are uploaded to storage and you receive a presigned URL with an expiry timestamp. Set inline: true to skip storage and get the base64-encoded result directly in the response body — useful when you need the bytes immediately or storage is unavailable.

---

Examples

Example: Multipart with options

curl -X POST https://morso.dev/api/optimize-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F 'options={"output_format":"webp","quality":80}'

{
  "url": "https://storage.morso.dev/optimized/a1b2c3d4.webp?token=xyz",
  "expires_at": "2026-05-05T12:00:00Z",
  "original_size": 524288,
  "optimized_size": 104857,
  "reduction_percent": 80.0,
  "output_format": "webp",
  "width": 1920,
  "height": 1080
}

Example: JSON with inline response

curl -X POST https://morso.dev/api/optimize-image/json \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "iVBORw0KGgoAAAANSUhEUgAA...",
    "output_format": "jpeg",
    "quality": 75,
    "inline": true
  }'

{
  "content": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "original_size": 245000,
  "optimized_size": 61250,
  "reduction_percent": 75.0,
  "output_format": "jpeg",
  "width": 1200,
  "height": 800
}

Example: Resize

curl -X POST https://morso.dev/api/optimize-image/json \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "iVBORw0KGgoAAAANSUhEUgAA...",
    "max_width": 800,
    "strip_metadata": true
  }'

{
  "url": "https://storage.morso.dev/optimized/e5f6g7h8.webp?token=abc",
  "expires_at": "2026-05-05T12:00:00Z",
  "original_size": 1048576,
  "optimized_size": 153600,
  "reduction_percent": 85.4,
  "output_format": "webp",
  "width": 800,
  "height": 533
}

Errors

• 503 — Storage unavailable and inline not set. Workaround: use inline: true to bypass storage entirely.

See Errors for the standard error shape.