Deploy and Host Images on Railway

Images is an HTTP API that crops, resizes, converts and compresses images. Your app sends an image and a JSON config in one request, and the response is the processed image. Any language that can send a multipart form can use it, so your app doesn't need a native image library.

Images reads JPEG, PNG, WebP, GIF, AVIF, TIFF and SVG files. It writes JPEG, PNG or WebP, or keeps the format of the source file.

About Hosting Images

The template deploys one stateless container. It needs no database, no volume and no other service.

The service reads two variables:

Variable	Default	Purpose
`API_KEY`	A random string that Railway generates on deploy	Every request to `/process-image` must send it as `Authorization: Bearer YOUR_API_KEY`. The service doesn't start without it.
`MAX_UPLOAD_MB`	`25`	The largest request body that the service accepts. Add this variable to change the limit.

After the deploy, open /docs on your domain. The page lists every config option and lets you send test requests from the browser. /openapi.json returns the same information as an OpenAPI document.

Common Use Cases

Each use case is one config value:

Use case	`config`
Thumbnail for a user upload	`{"resize":{"width":200,"height":200}}`
WebP version of a photo for a web page	`{"convert":{"format":"webp"},"compress":{"quality":80}}`
Square avatar from a region that the user picked	`{"crop":{"top":40,"left":120,"width":600,"height":600},"resize":{"width":256}}`
Smaller file in the same format	`{"compress":{"quality":70}}`

The operations always run in this order: crop, resize, convert, compress.

Send a request

Put the image in the file field and the operations in the config field:

curl -X POST "https://YOUR_DOMAIN/process-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'config={"resize":{"width":400},"convert":{"format":"webp"}}' \
  -F "file=@photo.jpg" \
  -o photo.webp

Replace the following:

YOUR_DOMAIN: the public domain of the service, from the Networking section of the service settings
YOUR_API_KEY: the value of API_KEY, from the Variables tab of the service

The response body is the processed image. If the config is invalid, the service answers 400 with a JSON message that names the field.

Dependencies for Images Hosting

Images has no external dependencies. The container includes everything that the service needs.

Why Deploy Images on Railway?

Image processing comes in bursts, and Railway bills for the CPU and memory that a service uses. If you turn on Serverless in the service settings, Railway puts Images to sleep when it gets no traffic, and you don't pay for compute while it sleeps. The first request after a sleep waits for the container to start.

Images can run in the same project as your app. Your app then reads the domain and the key through reference variables, so you never copy the key by hand:

IMAGES_URL=https://${{Images.RAILWAY_PUBLIC_DOMAIN}}
IMAGES_API_KEY=${{Images.API_KEY}}