quarkus-webp-api

Minimal REST-API for converting images to WebP powered by Quarkus.

---

Features

• Convert images of most common formats (JPEG, PNG, BMP, TIFF) to WebP
• Resizing images with aspect ratio preservation
• Quality setting for lossy WebP conversion
• Docker image with native executable for fast startup and low memory consumption
• Application configuration via environment variables

Usage

NOTE: Now you can try the API by using hosted instance at quarkus-webp-api.ivchenko.dev. There are no usage limits for now, but this instance may not be highly available or performant. Please, use it responsibly.

API Endpoint

The API exposes a single endpoint for image conversion:

POST /

Content-Type: multipart/form-data

Response Content-Type: image/webp

Request Parameters

Parameter	Type	Required	Description
file	File	Yes	The image file to convert (JPEG, PNG, BMP, or TIFF)
parameters	JSON	No	Optional JSON object with width, height, and/or quality for image processing

Parameters JSON Schema

{
  "width": 800,
  "height": 600,
  "quality": 80
}

• If only width is provided, height will be calculated to maintain aspect ratio
• If only height is provided, width will be calculated to maintain aspect ratio
• If both width and height are provided, the image will be resized to the exact dimensions
• If neither is provided, the image will be converted without resizing
• quality controls the WebP compression quality (0-100, where 100 is lossless). If not provided, defaults to 100

Error Responses

The API returns appropriate error messages in the following cases:

Error	Description
400 Bad Request	Missing file or invalid parameters (e.g., negative width/height, quality outside 0-100)
500 Internal Error	Failed to read or encode the image

Examples

Basic Conversion (no resizing)

curl -X POST http://localhost:8080/ \
  -F "file=@image.png" \
  -o output.webp

Convert with specific width (aspect ratio preserved)

curl -X POST http://localhost:8080/ \
  -F "file=@image.jpg" \
  -F 'parameters={"width": 800};type=application/json' \
  -o output.webp

Convert with specific height (aspect ratio preserved)

curl -X POST http://localhost:8080/ \
  -F "file=@image.png" \
  -F 'parameters={"height": 600};type=application/json' \
  -o output.webp

Convert with exact dimensions

curl -X POST http://localhost:8080/ \
  -F "file=@image.bmp" \
  -F 'parameters={"width": 800, "height": 600};type=application/json' \
  -o output.webp

Convert with custom quality

curl -X POST http://localhost:8080/ \
  -F "file=@image.jpg" \
  -F 'parameters={"quality": 75};type=application/json' \
  -o output.webp

Convert with resizing and custom quality

curl -X POST http://localhost:8080/ \
  -F "file=@image.png" \
  -F 'parameters={"width": 800, "quality": 80};type=application/json' \
  -o output.webp

Running with Docker

Using prebuilt GHCR image

docker run -p 8080:8080 ghcr.io/fakeivchenko/quarkus-webp-api:latest

Building image yourself

# Build the Docker image
docker build -t quarkus-webp-api .

# Run the container
docker run -p 8080:8080 quarkus-webp-api

License and contributing

This project is licensed under Unlicense license.

Issues and pull requests are always welcome! Feel free to contribute to this project.