API v1

Image Optimization API Documentation

Optimize JPEG, PNG, WebP, AVIF, HEIC, and HEIF images with a synchronous, no-retention HTTP API.

Optimize an image

Send a multipart request to POST /v1/images/optimize with an API key in the Bearer authorization header. A successful response contains the optimized image bytes.

curl --request POST \
  --url https://backend.optimizeyourimage.com/v1/images/optimize \
  --header "Authorization: Bearer oyi_live_your_key" \
  --header "Idempotency-Key: 8f32b13e-7aa8-4d65-b332-34e29a3629bc" \
  --form "[email protected]" \
  --form "output_format=webp" \
  --form "quality=80" \
  --output optimized.webp

Request fields

Field	Accepted values	Default
file	JPEG, PNG, WebP, AVIF, HEIC, or HEIF; 20 MB and 25 MP maximum	Required
output_format	webp, avif, jpeg, png	webp
quality	Integer from 1 to 100	80
max_width	Positive integer; images are never enlarged	Original
max_height	Positive integer; aspect ratio is preserved	Original
preserve_metadata	true or false	false

Limits and credits

One successful image consumes one credit; validation and processing failures do not.
Only the primary still image is processed from HEIC/HEIF containers.
Requests have a 30-second deadline and do not retain source or output files.
Use a unique Idempotency-Key when a request may be retried. A completed key prevents a second charge, but returns 409 because output bytes are never retained for replay.

Success response

The response body is the raw optimized image, not JSON. Read the following headers before saving it.

Header	Meaning
Content-Type	The actual JPEG, PNG, WebP, or AVIF media type.
Content-Disposition	A sanitized suggested output filename.
X-Request-Id	Safe identifier to include in a support request.
X-Input-Format	The format detected from the uploaded bytes.
X-Output-Format	The encoder that produced the response body.
X-Credits-Remaining	Available, unexpired credits after this successful image.

Node.js

const body = new FormData();
body.set("file", new Blob([await fs.readFile("photo.png")]), "photo.png");
body.set("output_format", "avif");
body.set("quality", "80");

const response = await fetch("https://backend.optimizeyourimage.com/v1/images/optimize", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.OYI_API_KEY,
    "Idempotency-Key": crypto.randomUUID(),
  },
  body,
});

if (!response.ok) throw new Error(await response.text());
await fs.writeFile("optimized.avif", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

with open("photo.jpg", "rb") as image:
    response = requests.post(
        "https://backend.optimizeyourimage.com/v1/images/optimize",
        headers={"Authorization": f"Bearer {os.environ['OYI_API_KEY']}"},
        files={"file": ("photo.jpg", image, "image/jpeg")},
        data={"output_format": "webp", "quality": 80},
        timeout=35,
    )

response.raise_for_status()
with open("optimized.webp", "wb") as output:
    output.write(response.content)

Errors

Errors use application/problem+json. A depleted balance returns 402, rate limiting returns 429, an oversized input returns 413, unsupported formats return 415, and malformed images return 422. Every response includes a request identifier for support and tracing.

Keys and billing

Sign in with Google or a magic link, then use the developer dashboard to create and revoke keys, inspect credits and usage, open hosted Polar checkout, or enter the customer portal. The authenticated supporting endpoints are POST /v1/api-keys, GET /v1/api-keys, DELETE /v1/api-keys/:id, POST /v1/billing/checkout, and POST /v1/billing/portal. API keys are shown once and stored only as hashes.