REST API

Lumen API Documentation

Integrate AI-powered image processing into your applications. Simple REST endpoints, pay-as-you-go pricing.

Authentication

All API requests require an API key passed via the Authorization header. Create API keys in your account dashboard.

curl -H "Authorization: Bearer mk_live_xxx" \
  https://api.lumen.dev/v1/upscale

Base URL

Production

https://api.lumen.dev

Development

http://localhost:3000

POST

/v1/upscale

Upload an image and receive the upscaled version. Supports JPEG, PNG, WebP, TIFF, and HEIC.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file (max 50MB)
scale	integer	No	Scale factor: 2, 3, 4, 5, 6, or 8 (default: 2)
model	string	No	AI model: real-esrgan, remacri, ultrasharp, or face-enhance (default: real-esrgan)
denoise	boolean	No	Apply noise reduction (default: false)
format	string	No	Output format: png, webp, jpeg, or avif (default: png)

Response Headers

Header	Description
X-Result-Width	Output image width in pixels
X-Result-Height	Output image height in pixels
X-Scale	Applied scale factor
X-Engine	Processing engine used (sharp or upscayl-ncnn)

Example

curl -X POST https://api.lumen.dev/v1/upscale \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.jpg" \
  -F "scale=4" \
  -F "model=real-esrgan" \
  -F "denoise=true" \
  -o upscaled.png

POST

/tools/convert

Convert images between JPEG, PNG, WebP, AVIF, TIFF, and GIF formats.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to convert
format	string	No	Output format: jpeg, png, webp, avif, tiff, gif (default: png)
quality	integer	No	Output quality (1-100) (default: 95)

Example

curl -X POST https://api.lumen.dev/tools/convert \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.png" \
  -F "format=webp" \
  -F "quality=90" \
  -o converted.webp

POST

/tools/compress

Optimize images with smart format-aware compression. Uses mozjpeg for JPEG, palette quantization for PNG, and near-lossless for WebP.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to compress
quality	integer	No	Compression quality (1-100) (default: 80)

Example

curl -X POST https://api.lumen.dev/tools/compress \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.jpg" \
  -F "quality=75" \
  -o compressed.jpg

POST

/tools/remove-background

Remove image backgrounds using corner-sampling color distance analysis. Produces transparent PNG output.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to process

Example

curl -X POST https://api.lumen.dev/tools/remove-background \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@product.jpg" \
  -o no-bg.png

POST

/tools/crop

Crop, rotate, flip, and resize images with multiple fit modes and gravity options.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to process
rotate	number	No	Rotation in degrees (-180 to 180) (default: 0)
flipH	boolean	No	Flip horizontally (default: false)
flipV	boolean	No	Flip vertically (default: false)
resizeWidth	integer	No	Target width in pixels
resizeHeight	integer	No	Target height in pixels
fit	string	No	Fit mode: cover, contain, fill, inside, outside (default: cover)
gravity	string	No	Gravity: center, north, south, east, west (default: center)
format	string	No	Output format: png, webp, jpeg, avif (default: png)

Example

curl -X POST https://api.lumen.dev/tools/crop \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.jpg" \
  -F "rotate=90" \
  -F "resizeWidth=800" \
  -F "resizeHeight=600" \
  -F "fit=cover" \
  -o resized.png

POST

/tools/watermark

Add text watermarks with customizable position, font size, color, opacity, and optional tiling.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to watermark
watermarkText	string	No	Text content for the watermark (default: Watermark)
fontSize	integer	No	Font size in pixels (default: 48)
fontColor	string	No	Font color (hex) (default: #ffffff)
position	string	No	Position: northwest, north, northeast, west, center, east, southwest, south, southeast (default: southeast)
opacity	number	No	Opacity (0-1) (default: 0.5)
tiled	boolean	No	Tile watermark across the image (default: false)
format	string	No	Output format: png, webp, jpeg, avif (default: png)

Example

curl -X POST https://api.lumen.dev/tools/watermark \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.jpg" \
  -F "watermarkText=© Lumen" \
  -F "fontSize=24" \
  -F "position=southeast" \
  -F "opacity=0.3" \
  -o watermarked.png

POST

/tools/adjust

Adjust brightness, contrast, saturation, hue, and apply preset filters like sepia, warm, cool, and vintage.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to adjust
brightness	number	No	Brightness (0-200, where 100 is normal) (default: 100)
contrast	number	No	Contrast (0-200, where 100 is normal) (default: 100)
saturation	number	No	Saturation (0-200, where 100 is normal) (default: 100)
hue	number	No	Hue rotation (0-360 degrees) (default: 0)
preset	string	No	Preset filter: original, grayscale, sepia, warm, cool, highcontrast, fade, vintage (default: original)
negate	boolean	No	Invert all colors (default: false)
autoEnhance	boolean	No	Auto-enhance using histogram stretching (default: false)
format	string	No	Output format: png, webp, jpeg, avif (default: png)

Example

curl -X POST https://api.lumen.dev/tools/adjust \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.jpg" \
  -F "brightness=110" \
  -F "contrast=120" \
  -F "preset=warm" \
  -o enhanced.png

POST

/tools/info

Retrieve comprehensive image metadata including format, dimensions, color space, DPI, channel statistics, and EXIF data.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to analyze

Example

curl -X POST https://api.lumen.dev/tools/info \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.jpg"

POST

/tools/social

Resize images to exact dimensions for Instagram, Facebook, Twitter/X, LinkedIn, YouTube, Pinterest, and TikTok.

Request Body (multipart/form-data)

Field	Type	Required	Description
image	File	Yes	Image file to resize
preset	string	No	Platform preset: instagram-square, instagram-portrait, instagram-landscape, instagram-story, facebook-post, facebook-cover, twitter-post, twitter-header, linkedin-post, linkedin-cover, youtube-thumbnail, pinterest-pin, tiktok (default: instagram-square)
fit	string	No	Fit mode: cover, contain, fill (default: cover)
backgroundColor	string	No	Background color for contain mode (hex) (default: #000000)
format	string	No	Output format: png, webp, jpeg, avif (default: png)
quality	integer	No	Output quality (1-100) (default: 95)

Example

curl -X POST https://api.lumen.dev/tools/social \
  -H "Authorization: Bearer mk_live_xxx" \
  -F "image=@photo.jpg" \
  -F "preset=instagram-square" \
  -F "fit=cover" \
  -o social.png

GET

/v1/usage

Returns current usage statistics including daily limit, monthly count, and Pro status.

Response

{
  "used": 3,
  "limit": 3,
  "remaining": 0,
  "isPro": false,
  "thisMonth": 47,
  "allTime": 312
}

GET

/v1/account

Returns the authenticated user's account details including email and Pro status.

Response

{
  "user": {
    "id": "usr_abc123",
    "email": "you@example.com",
    "isPro": true,
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

POST

/v1/auth/magic-link

Send a passwordless sign-in link to an email address. No API key required.

Request Body (JSON)

{
  "email": "you@example.com"
}

Example

curl -X POST https://api.lumen.dev/v1/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Rate Limits

Rate limits are enforced per API key. Anonymous requests (no key) are limited to 3/day.

Free Tier

3 requests/day

Pro Tier

Unlimited

Error Response

HTTP/1.1 429 Too Many Requests
{
  "error": "Rate limit exceeded. Upgrade to Pro for unlimited access.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Error Codes

Code	Status	Description
MISSING_IMAGE	400	No image file provided
INVALID_FORMAT	400	Unsupported image format
FILE_TOO_LARGE	400	Image exceeds 50MB limit
RATE_LIMIT_EXCEEDED	429	Daily limit reached
PROCESSING_FAILED	500	Image processing error

Pricing

Pay-as-you-go at $0.05 per upscale. No minimums, no monthly commitments. Pro subscription ($9/mo) includes unlimited API calls for all endpoints.

Get API Key OpenAPI Spec (JSON)

Field

Type

Required

Description

image

File

Yes

Image file (max 50MB)

scale

integer

Scale factor: 2, 3, 4, 5, 6, or 8 (default: 2)

model

string

AI model: real-esrgan, remacri, ultrasharp, or face-enhance (default: real-esrgan)

denoise

boolean

Apply noise reduction (default: false)

format

string

Output format: png, webp, jpeg, or avif (default: png)

Header

Description

X-Result-Width

Output image width in pixels

X-Result-Height

Output image height in pixels

X-Scale

Applied scale factor

X-Engine

Processing engine used (sharp or upscayl-ncnn)

curl -X POST https://api.lumen.dev/v1/upscale \ -H "Authorization: Bearer mk_live_xxx" \ -F "image=@photo.jpg" \ -F "scale=4" \ -F "model=real-esrgan" \ -F "denoise=true" \ -o upscaled.png

Field

Type

Required

Description

image

File

Yes

Image file to convert

format

string

Output format: jpeg, png, webp, avif, tiff, gif (default: png)

quality

integer

Output quality (1-100) (default: 95)

Field

Type

Required

Description

image

File

Yes

Image file to compress

quality

integer

Compression quality (1-100) (default: 80)

Field

Type

Required

Description

image

File

Yes

Image file to process

Field

Type

Required

Description

image

File

Yes

Image file to process

rotate

number

Rotation in degrees (-180 to 180) (default: 0)

flipH

boolean

Flip horizontally (default: false)

flipV

boolean

Flip vertically (default: false)

resizeWidth

integer

Target width in pixels

resizeHeight

integer

Target height in pixels

fit

string

Fit mode: cover, contain, fill, inside, outside (default: cover)

gravity

string

Gravity: center, north, south, east, west (default: center)

format

string

Output format: png, webp, jpeg, avif (default: png)

curl -X POST https://api.lumen.dev/tools/crop \ -H "Authorization: Bearer mk_live_xxx" \ -F "image=@photo.jpg" \ -F "rotate=90" \ -F "resizeWidth=800" \ -F "resizeHeight=600" \ -F "fit=cover" \ -o resized.png

Field

Type

Required

Description

image

File

Yes

Image file to watermark

watermarkText

string

Text content for the watermark (default: Watermark)

fontSize

integer

Font size in pixels (default: 48)

fontColor

string

Font color (hex) (default: #ffffff)

position

string

Position: northwest, north, northeast, west, center, east, southwest, south, southeast (default: southeast)

opacity

number

Opacity (0-1) (default: 0.5)

tiled

boolean

Tile watermark across the image (default: false)

format

string

Output format: png, webp, jpeg, avif (default: png)

curl -X POST https://api.lumen.dev/tools/watermark \ -H "Authorization: Bearer mk_live_xxx" \ -F "image=@photo.jpg" \ -F "watermarkText=© Lumen" \ -F "fontSize=24" \ -F "position=southeast" \ -F "opacity=0.3" \ -o watermarked.png

Field

Type

Required

Description

image

File

Yes

Image file to adjust

brightness

number

Brightness (0-200, where 100 is normal) (default: 100)

contrast

number

Contrast (0-200, where 100 is normal) (default: 100)

saturation

number

Saturation (0-200, where 100 is normal) (default: 100)

hue

number

Hue rotation (0-360 degrees) (default: 0)

preset

string

Preset filter: original, grayscale, sepia, warm, cool, highcontrast, fade, vintage (default: original)

negate

boolean

Invert all colors (default: false)

autoEnhance

boolean

Auto-enhance using histogram stretching (default: false)

format

string

Output format: png, webp, jpeg, avif (default: png)

curl -X POST https://api.lumen.dev/tools/adjust \ -H "Authorization: Bearer mk_live_xxx" \ -F "image=@photo.jpg" \ -F "brightness=110" \ -F "contrast=120" \ -F "preset=warm" \ -o enhanced.png

Field

Type

Required

Description

image

File

Yes

Image file to analyze

Field

Type

Required

Description

image

File

Yes

Image file to resize

preset

string

Platform preset: instagram-square, instagram-portrait, instagram-landscape, instagram-story, facebook-post, facebook-cover, twitter-post, twitter-header, linkedin-post, linkedin-cover, youtube-thumbnail, pinterest-pin, tiktok (default: instagram-square)

fit

string

Fit mode: cover, contain, fill (default: cover)

backgroundColor

string

Background color for contain mode (hex) (default: #000000)

format

string

Output format: png, webp, jpeg, avif (default: png)

quality

integer

Output quality (1-100) (default: 95)

Code

Status

Description

MISSING_IMAGE

400

No image file provided

INVALID_FORMAT

400

Unsupported image format

FILE_TOO_LARGE

400

Image exceeds 50MB limit

RATE_LIMIT_EXCEEDED

429

Daily limit reached

PROCESSING_FAILED

500

Image processing error