REST API Reference

A hosted Cloudflare Worker that processes images over HTTP. No SDK required — POST an image, receive a transformed image.

Interactive API Reference (try it live): imgcraft-api.imgcraft.workers.dev/docs

Base URL: https://imgcraft-api.imgcraft.workers.dev

Endpoints

Method	Path	Description
`POST`	`/transform`	Process an image, returns transformed bytes
`GET`	`/info`	Read metadata without processing
`GET`	`/health`	Status check

POST /transform

Process an image with a pipeline of operations.

Content-Type: multipart/form-data

Fields

Field	Type	Description
image	`File`	The image to process. Required.
ops	`string (JSON)`	Array of operation objects. See ops schema below.

Response

Content-Type: image/webp (or the requested format)
Body: processed image bytes

ops JSON schema

Each operation is an object with an op field plus operation-specific parameters:

[
  { "op": "resize", "options": { "width": 800, "height": 600, "fit": "cover" } },
  { "op": "format", "options": { "format": "webp", "quality": 85 } },
  { "op": "grayscale" },
  { "op": "removeBackground" }
]

[
  { "op": "resize", "options": { "width": 800, "height": 600, "fit": "cover" } },
  { "op": "format", "options": { "format": "webp", "quality": 85 } },
  { "op": "grayscale" },
  { "op": "removeBackground" }
]

Supported operations

op	options
`resize`	`width`, `height`, `fit`
`crop`	`left`, `top`, `width`, `height`
`rotate`	`angle`
`flip`	—
`flop`	—
`format`	`format` (`jpeg`, `png`, `webp`, `avif`), `quality`
`blur`	`sigma`
`sharpen`	—
`grayscale`	—
`tint`	`r`, `g`, `b`
`negate`	—
`brightness`	`brightness`
`contrast`	`value`
`saturation`	`saturation`
`compress`	`format` (`jpeg`, `png`, `webp`, `avif`), `quality`, `effort`
`removeBackground`	—
`upscale`	`factor` (2 or 4)
`smartCrop`	`subject` (`face`, `object`)
`stripMeta`	—

Example (curl)

curl -X POST https://imgcraft-api.imgcraft.workers.dev/transform \
  -F "image=@photo.jpg" \
  -F 'ops=[{"op":"resize","options":{"width":800}},{"op":"format","options":{"format":"webp","quality":85}}]' \
  --output result.webp

curl -X POST https://imgcraft-api.imgcraft.workers.dev/transform \
  -F "image=@photo.jpg" \
  -F 'ops=[{"op":"resize","options":{"width":800}},{"op":"format","options":{"format":"webp","quality":85}}]' \
  --output result.webp

Example (fetch)

const form = new FormData()
form.append('image', file)
form.append('ops', JSON.stringify([
  { op: 'resize', options: { width: 800 } },
  { op: 'format', options: { format: 'webp', quality: 85 } },
]))

const res = await fetch('https://imgcraft-api.imgcraft.workers.dev/transform', {
  method: 'POST',
  body: form,
})

const blob = await res.blob()

const form = new FormData()
form.append('image', file)
form.append('ops', JSON.stringify([
  { op: 'resize', options: { width: 800 } },
  { op: 'format', options: { format: 'webp', quality: 85 } },
]))

const res = await fetch('https://imgcraft-api.imgcraft.workers.dev/transform', {
  method: 'POST',
  body: form,
})

const blob = await res.blob()

GET /info

Read image metadata without processing. Accepts a URL query parameter.

GET /info?url=https://example.com/photo.jpg

GET /info?url=https://example.com/photo.jpg

Or POST with a file:

POST /info
Content-Type: multipart/form-data

image: File

POST /info
Content-Type: multipart/form-data

image: File

Response

{
  "width": 3840,
  "height": 2160,
  "format": "jpeg",
  "channels": 3,
  "hasAlpha": false,
  "size": 4521823
}

{
  "width": 3840,
  "height": 2160,
  "format": "jpeg",
  "channels": 3,
  "hasAlpha": false,
  "size": 4521823
}

GET /health

GET /health

GET /health

{ "status": "ok", "version": "1.0.0" }

{ "status": "ok", "version": "1.0.0" }

Rate limiting

Requests are rate-limited by IP address with three tiers:

Tier	Limit	Window	Error code
Per-minute	10 requests	60 seconds	`RATE_LIMIT_EXCEEDED`
Per-day	50 requests	24 hours	`RATE_LIMIT_DAY_EXCEEDED`
AI ops per-day	10 requests	24 hours	`RATE_LIMIT_AI_EXCEEDED`

The AI tier applies only to requests containing removeBackground, smartCrop, or upscale operations.

Other limits: 10 MB max image size, 30 second processing timeout.

Exceeding any tier returns HTTP 429 with a Retry-After header (seconds until the window resets).

Errors

All errors return JSON:

{
  "error": "Invalid image format",
  "code": "INVALID_FORMAT"
}

{
  "error": "Invalid image format",
  "code": "INVALID_FORMAT"
}

The API is intended for moderate usage. For high-volume workloads, use the imgcraft npm library directly in your own infrastructure.