Welcome to the theGlitch API

theGlitch offers 14 image transforms from a single platform — for developers and creators alike. Fast edits (resize, format, watermark) and AI-powered transforms (background removal, upscale, colorize) all share the same API.

Whichever channel you use, the result and price are the same:

Create an account, get a key, send your first request — 60 seconds.

1. Get an API key

   Panel → API Keys → New key. Your access key is a unique 32-character string.

2. Send your first request

   Resize an image to 800px wide:

   ~/glitch · curl

   curl "https://theglitch.app/api/v1/resize?url=https://theglitch.app/showcase/resize-before.webp&width=800" \  -H "X-Api-Key: YOUR_API_KEY" \  -o result.webp

3. Get the response

   Response: 200 OK + processed image (binary), written to result.webp.

4. Try more

   All 14 processing endpoints are below: API Reference.

All processing requests are authenticated with the X-Api-Key header. View and copy your access keys from the panel. How many keys you can hold at once depends on your plan: Free and Starter 1, Pro 5, Business 20. On plans that allow several keys you rotate without downtime by creating a new key and revoking the old one; on single-key plans you must revoke first and then create, and requests in between return 401.

curl "https://theglitch.app/api/v1/resize?width=800" \  -H "X-Api-Key: YOUR_API_KEY" \  -F "file=@photo.jpg" -o result.webp

There are 4 ways to send an image to the API. Every processing endpoint accepts all four. If you send more than one, this order wins: form file → url → image → binary body; in a form upload only the first file is read.

1. 1 · URL

   Pass a public http(s) address via the url query parameter. Localhost, private and internal-network addresses are refused; up to 5 redirects are followed; a non-2xx source response returns 400 INVALID_INPUT. The download is capped at 10 s / 25 MB and our requests carry the TheGlitch/1.0 User-Agent. URL inputs are cached for 60 minutes.

2. 2 · Base64

   The image field in a JSON body (data-URI supported): Content-Type: application/json.

3. 3 · Binary body

   Send raw bytes directly in the body with an image/* Content-Type.

4. 4 · Form upload

   Upload a file via the multipart file field.

# 1) URL
curl "https://theglitch.app/api/v1/resize?url=https://theglitch.app/showcase/resize-before.webp&width=800" -H "X-Api-Key: KEY" -o out.webp

# 2) Base64 (JSON body)
curl -X POST "https://theglitch.app/api/v1/resize?width=800" -H "X-Api-Key: KEY" \
  -H "Content-Type: application/json" -d '{"image":"data:image/jpeg;base64,/9j/4AAQ..."}' -o out.webp

# 3) Binary body
curl -X POST "https://theglitch.app/api/v1/resize?width=800" -H "X-Api-Key: KEY" \
  -H "Content-Type: image/jpeg" --data-binary @photo.jpg -o out.webp

# 4) Form upload
curl -X POST "https://theglitch.app/api/v1/resize?width=800" -H "X-Api-Key: KEY" -F "file=@photo.jpg" -o out.webp

14 processing endpoints (plus the read-only /v1/info). They share the same authentication and, except for /v1/image-info, return a binary image.

GET POST /v1/process

The main endpoint that combines everything in one request: resize, effects, rotation, watermark, format conversion and presets together. Any combination still counts as 1 request.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/process?url=https://theglitch.app/showcase/resize-before.webp&width=800&format=webp&brightness=10&sharpen=20" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• AI flags like removeBackground, upscale, colorize are also accepted — see the AI endpoint sections. Requests using an AI flag count against the AI quota.
• POST + JSON body is supported; query string values take precedence for url/image/width/height.

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/resize

Resizes the image to target dimensions. Provide at least one of width/height; mode controls cropping.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/resize?url=https://theglitch.app/showcase/resize-before.webp&width=800&height=600&mode=fill" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• Output resolution is plan-limited (Free 2048px, Starter 4000px, Pro+ 8000px). An explicit width/height above the limit returns VALIDATION_ERROR. If you request no resize and the source is larger than the limit, the output is scaled down to fit it, preserving the aspect ratio.

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/convert

Converts the image to another format. Without format, auto behavior applies (Accept header → WebP default).

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/convert?url=https://theglitch.app/showcase/resize-before.webp&format=webp&quality=80" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• GIF output is served as PNG. TIFF and AVIF are available on paid plans — see File Formats.

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/effects

Brightness, contrast, saturation, blur, sharpen, grayscale, sepia plus rotate/flip. All effects can be combined in a single request.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/effects?url=https://theglitch.app/showcase/resize-before.webp&brightness=15&contrast=20&sharpen=25" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• Rotation and flips are applied before effects and resizing.
• If grayscale and sepia are both set, grayscale wins.

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/watermark

Adds a text watermark. 5 positions, custom color, size and opacity.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/watermark?url=https://theglitch.app/showcase/resize-before.webp&watermarkText=theGlitch.app&watermarkPosition=center&watermarkOpacity=40" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• watermarkText is required and must be sent in the query string; if empty, MISSING_WATERMARK is returned.
• The watermark is applied before resizing; combine with other operations via /process.

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/optimize

Automatic web optimization: output is WebP unless a format is specified, default quality 85.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/optimize?url=https://theglitch.app/showcase/resize-before.webp&quality=80" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• If a format parameter is provided, it overrides the WebP default.

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/preset/{name}

Applies a social media size preset. name is a path parameter (case-insensitive, underscore naming). All presets use mode=fill (center crop).

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Available presets

Example

curl "https://theglitch.app/api/v1/preset/og_image?url=https://theglitch.app/showcase/resize-before.webp" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o og.webp

• An unknown name returns INVALID_PRESET along with the list of valid presets.
• Combine with effect/format parameters: /preset/og_image?url=…&brightness=10&format=jpeg

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/image-infoJSON response

Returns image metadata. Unlike every other endpoint, the response is JSON, not binary (Content-Type: application/json).

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Response fields

{
  "width": 1920,
  "height": 1080,
  "format": "jpeg",
  "colorType": "rgb",
  "hasAlpha": false,
  "orientation": 1,
  "fileSize": 245760,
  "fileSizeHuman": "240.0 KB"
}

Example

curl "https://theglitch.app/api/v1/image-info?url=https://theglitch.app/showcase/resize-before.webp" \
  -H "X-Api-Key: YOUR_API_KEY"

• This endpoint does not process the image; it only decodes and inspects it. Counts as 1 request.

Each successful call counts as 1 request against your monthly quota (a combo of effects + resize + format is still 1).

GET POST /v1/remove-bgGPU · counts against AI quota

Removes the background with AI; the result has a transparent background.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/remove-bg?url=https://theglitch.app/showcase/bg-before.webp" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.png

• With format=auto the output is forced to PNG to preserve transparency. An explicit format wins.

Each successful call consumes 1 from your monthly AI quota only; it does not count against the request quota. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/upscaleGPU · counts against AI quota

Upscales resolution 2x or 4x with AI; sharpens low-resolution images.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/upscale?url=https://theglitch.app/showcase/up-before.webp&upscaleScale=4" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• Combine with effects, watermark or format: /upscale?url=…&upscaleScale=2&sharpen=20&format=webp
• Two separate limits apply: (1) the source image cannot exceed 2.1 megapixels (1448×1448) — this limit is independent of the scale factor; (2) the upscaled size (source × factor) must stay within your plan's resolution limit — on Free (2048px) that means sources up to 512px for 4×, or 1024px for 2×. If either is exceeded, VALIDATION_ERROR is returned before the AI runs and no AI quota is used.

Each successful call consumes 1 from your monthly AI quota only; it does not count against the request quota. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/colorizeGPU · counts against AI quota

Brings black & white or faded photos to natural color with AI.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/colorize?url=https://theglitch.app/showcase/color-before.webp" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

Each successful call consumes 1 from your monthly AI quota only; it does not count against the request quota. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/face-restoreGPU · counts against AI quota

Restores blurry, low-resolution or degraded faces with AI.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/face-restore?url=https://theglitch.app/showcase/face-before.webp" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• Whatever the input measures, the output is normalized to about 1 megapixel; the aspect ratio and the orientation are roughly preserved. Sending a larger source does not produce a larger result — keep your original. Very wide or very tall images (a panorama, say) can come back noticeably reshaped.

Each successful call consumes 1 from your monthly AI quota only; it does not count against the request quota. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/restoreGPU · counts against AI quota

Repairs old, damaged or faded photographs with AI; age-related degradation is fixed automatically.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/restore?url=https://theglitch.app/showcase/feat-photo-before.webp&withScratch=true" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• Use withScratch=true if the photo has physical damage like scratches or tears.
• Whatever the input measures, the output is normalized to about 1 megapixel; the aspect ratio and the orientation are roughly preserved. Sending a larger source does not produce a larger result — keep your original. Very wide or very tall images (a panorama, say) can come back noticeably reshaped.

Each successful call consumes 1 from your monthly AI quota only; it does not count against the request quota. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/remove-objectGPU · counts against AI quota

Removes masked objects with AI and fills the background naturally.

Parameters

Input can be url, image (base64), file (form) or a raw binary body — see Input Methods.

Example

curl "https://theglitch.app/api/v1/remove-object?url=https://theglitch.app/showcase/obj-before.webp&mask=YOUR_MASK_URL" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• mask is required. Send a URL in the query string, or base64 data in the mask field of a JSON body (POST); if it is missing, MISSING_MASK is returned.
• To prepare a mask, paint the areas to remove white in any editor and save as a PNG with the same dimensions as the source.

Each successful call consumes 1 from your monthly AI quota only; it does not count against the request quota. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

Monthly request quotas depend on your plan. AI requests are tracked against a separate AI quota. There is no per-minute rate limit; quotas reset on the 1st of each month (UTC).

• A single request combining resize + 5 effects + format conversion = 1 request.
• AI endpoints (remove-bg, upscale, colorize, face-restore, restore, remove-object) consume 1 from the AI quota only; they do not count against the request quota.
• Only successful (2xx) responses count against your quota.
• URL inputs are cached for 60 minutes (the window refreshes on each hit); an identical request returns instantly without reprocessing. Cached responses do not count against your quota and carry no X-Glitch-Processing-Time.
• When your request quota runs out, AI requests stop too: you get 429 REQUEST_QUOTA_EXCEEDED even if your AI quota is untouched.

Responses include custom headers so you can monitor your usage:

Error responses are always JSON; successful responses are binary images. If the response Content-Type starts with image/, the request succeeded; application/json means an error (one exception: /image-info returns JSON on success too).

Error response format

{
  "error": true,
  "code": "INVALID_INPUT",
  "message": "No image input provided. Use url, image (base64), file upload, or binary body."
}

Receiving long-running AI results via webhooks is on our roadmap — coming soon. The draft below shows the planned payload shape.

{  "event": "transform.completed",  "job_id": "job_8f3a91",  "endpoint": "/v1/upscale",  "status": "ok",  "duration_ms": 3214,  "result_url": "https://cdn.theglitch.app/r/8f3a91.png"}

All release notes