REST API Server (serve)

v0.2.0-beta

Run a local self-hosted HTTP microservice for backend applications and Docker containers.

Run imagerry serve to spin up a high-performance local HTTP REST API server. Perfect for Node.js, Python, Go, Ruby, and PHP backend services.

Start the API Server

|bash

# Start on default port 5273
imagerry serve

# Start on custom port
imagerry serve -P 8080

HTTP Endpoints Reference

`POST /api/v1/process`

Accepts multipart/form-data with an image file and optional preset configuration.

|bash

curl -f -X POST http://localhost:5273/api/v1/process \
  -F "image=@screenshot.png" \
  -F 'preset={"padding": 64, "bgColor": "#18181b"}' \
  --output result.png

|javascript

import fs from 'node:fs';

const formData = new FormData();
formData.append('image', new Blob([fs.readFileSync('screenshot.png')]), 'screenshot.png');
formData.append('preset', 'mesh');

const res = await fetch('http://localhost:5273/api/v1/process', {
  method: 'POST',
  body: formData,
});

const buffer = Buffer.from(await res.arrayBuffer());
fs.writeFileSync('result.png', buffer);

|python

import requests

with open('screenshot.png', 'rb') as f:
    files = {'image': f}
    data = {'preset': 'mesh'}
    res = requests.post('http://localhost:5273/api/v1/process', files=files, data=data)
    
    with open('result.png', 'wb') as out:
        out.write(res.content)

`GET /health`

Returns JSON status and active engine version:

|json

{
  "status": "ok",
  "version": "0.2.0-beta""
}

`GET /presets`

Returns an array of all built-in named presets:

|json

[
  "default",
  "mesh",
  "gradient"
]

`GET /template`

Returns the default preset configuration object with all available settings keys.

`GET /docs`

Interactive browser-based API documentation and live endpoint runner.

Warning

cURL Fail Flag Recommendation

Always include the -f (or --fail-with-body) flag when using curl with --output. This ensures that if the server returns a JSON error, curl will not save the error JSON directly into your image file.

Found an issue or typo? Report on GitHub

Imagerry CLI Docs • v0.2.0-beta