POST AI agent ready /v1/image/resize

Image Resize API - CSS Dimensions and Metadata Helper

Accepts a url or base64 image plus a target width (and optional height) and returns content type, size in bytes, target dimensions, and a ready-to-paste CSS fragment (width, height, object-fit). Pixel resizing itself is performed client-side via Canvas or server-side via Sharp; this endpoint provides the sizing scaffolding.

Endpoint

Code examples

curl -X POST https://api.botoi.com/v1/image/resize \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hero.jpg","width":400,"height":300}'

When to use this API

Scaffold responsive image tags

When a CMS editor picks a target size, call this endpoint and drop the returned css_resize onto the <img> tag. Consistent sizing without hand-tuning CSS.

Pre-flight image imports

Before storing a remote image, fetch its size_bytes and content_type. Reject files larger than your quota without downloading the body (HEAD request only).

Aspect-ratio enforcement

Combine with /v1/image/metadata to check actual dimensions and compare against the target. Warn users when the aspect ratio mismatch will cause cropping under object-fit:cover.

Frequently asked questions

Why doesn't this return a resized image?

Pixel-level resizing needs a native library (Sharp, libvips) that doesn't run in edge Workers without WASM. The endpoint provides dimensions and CSS for client-side scaling. Run true resizing on a regular server when you need baked-in pixels.

What does target_height:null mean?

You passed only width. Apply the css_resize with width:Npx; the height auto-scales to preserve aspect ratio.

Does this follow redirects on the URL?

The HEAD request uses default redirect behavior. If your URL chain is long, use /v1/link/expand to resolve the final target first.

What about base64 dimensions?

The endpoint reports size in bytes but not pixel dimensions for base64 (it does not decode the image). For pixel dimensions pre-upload, inspect the image client-side and send the result.

What is the request timeout?

The HEAD request has no explicit timeout beyond the Workers default. Very slow origins may stall; retry on failure.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.