Welcome to the theGlitch API

theGlitch offers 19 image transforms from a single platform — for developers and creators alike. Fast edits (resize, format, watermark, vectorize to SVG) and AI-powered transforms (background removal, upscale, colorize, image to text, product scene, listing copy) 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 19 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

19 processing endpoints (plus the read-only /v1/info). They share the same authentication. /v1/image-info and /v1/listing-copy return JSON, /v1/ocr returns JSON by default, /v1/vectorize returns SVG; the rest 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 and colorize are also accepted — see the AI endpoint sections. Only ONE AI flag is allowed per request; more than one returns 400 MULTIPLE_AI_OPERATIONS, so chain AI operations with separate requests. An AI flag must be a plain query parameter or a top-level field of a UTF-8 JSON body. Requests using an AI flag deduct AI credits.
• 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/vectorizeSVG response

Turns a flat-color logo or icon into a scalable SVG vector. It runs on our own servers: it counts as 1 request against your quota, not against AI credits. The response is image/svg+xml.

Parameters

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

Response headers

Example

curl "https://theglitch.app/api/v1/vectorize?url=https://theglitch.app/logo-512.png&colors=4&curves=polygon" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o logo.svg

• Works best for flat-color logos and icons; heavy gradients come out simplified. It is not meant for turning photos into vectors: a photo-like, very detailed image is refused with 400 VALIDATION_ERROR.
• Turkish letters in a logo (Ç, Ğ, İ, Ö, Ş, Ü) keep their dots and cedillas; the lettering comes back as shapes (paths), not as editable text.
• Input is PNG, JPEG or WebP; at most 4 megapixels, longest edge 4096 px. A photo-like image is refused before vectorizing starts and costs nothing; if vectorizing has run and the output turns out too detailed to serve, you also get 400 VALIDATION_ERROR, and that request counts as 1 request against your quota.
• The output is cleaned: DTDs, scripts, event attributes and external links are removed and only basic shape elements remain; ids get a per-request prefix and the root element always has a viewBox.
• The image is not written to persistent storage: temporary files are kept in memory only and deleted as soon as processing finishes.

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

GET POST /v1/remove-bgAI · 1 credit

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.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/upscaleAI · 1 credit

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 credits are used.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/colorizeAI · 1 credit

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

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/face-restoreAI · 9 credits

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.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/restoreAI · 9 credits

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" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o result.webp

• Scratch, tear and stain repair is automatic; no separate parameter is needed for it.
• 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.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/remove-objectAI · 1 credit

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.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/headshotAI · 9 credits

Generates a studio-style professional headshot from a portrait photo with AI — for CVs, LinkedIn and company team pages. The result is an image; format and quality apply as on the other AI endpoints.

Parameters

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

Example

curl "https://theglitch.app/api/v1/headshot?url=https://theglitch.app/showcase/det-face-s3-before.webp&background=office&aspectRatio=3:4" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o headshot.webp

• This is NOT a biometric ID photo: it cannot be used for passports, ID cards, driving licences or official applications.
• Only send your own photo, or a photo of someone who has given you permission (terms of use).
• No gender or similar attribute is asked for; the headshot is generated from the uploaded photo.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/ocrAI · 1 creditJSON response

Reads the text in an image with AI: receipts, invoices, menus, business cards, old documents. The default response is JSON (text, markdown, blocks, warnings); use output to get plain text, Markdown, HTML, CSV, Word (DOCX) or PDF.

Parameters

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

Output formats

JSON fields (output=json)

Example: an image that contains a table with its own printed header row (Ürün, Tutar). A table is returned as a table only when the image prints a header row; receipt items and price lists come back as plain lines.

{
  "text": "KAHVE EVİ\n\nFiş No: 0042\n\nÜrün\tTutar\nTürk kahvesi\t60,00\nSu\t15,00\n",
  "markdown": "# KAHVE EVİ\n\nFiş No: 0042\n\n| Ürün | Tutar |\n|---|---|\n| Türk kahvesi | 60,00 |\n| Su | 15,00 |\n",
  "blocks": [
    { "type": "heading", "level": 1, "text": "KAHVE EVİ" },
    { "type": "paragraph", "text": "Fiş No: 0042" },
    { "type": "table", "rows": [["Ürün", "Tutar"], ["Türk kahvesi", "60,00"], ["Su", "15,00"]] }
  ],
  "warnings": []
}

Example

curl "https://theglitch.app/api/v1/ocr?url=https://theglitch.app/showcase/det-ocr-hero-before.webp&output=json" \
  -H "X-Api-Key: YOUR_API_KEY"

• The output is a draft: check it against the original image before you use it, especially numbers, names and tables.
• The input is a single image; PDF input is not accepted. Send a multi-page document page by page as images — each image is a separate request and is charged separately.
• csv: only tables the image prints with their own header row are written as tables, row by row. Receipts and price lists are not treated as tables and stay as plain lines; if there is no table, no error is returned — each line of text becomes a single-column (text) row. The file is UTF-8 with a BOM; the default delimiter is a semicolon, for Turkish Excel (csvDelimiter).
• docx and pdf return a file to download (Content-Disposition: attachment; filename="ocr.docx" / "ocr.pdf"). The PDF is the extracted text re-typeset, with an embedded font for Turkish characters; the original image is not included.
• warnings carries fixed keys: truncated (the output looks cut short or stuck repeating; text may be missing or duplicated), fallback_used (the first reading looked unusable and the image was read again), low_confidence (no text was found, or it could not be read reliably). An empty array means no warnings. The same keys also arrive, comma-separated, in the X-Glitch-Warnings response header for every output format; the header is absent when there are no warnings.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/listing-copyAI · 1 creditJSON response

Writes a Turkish marketplace listing draft from a product photo (Trendyol, Hepsiburada, n11 format). The response is JSON: title, description, features, color, material, keywords, altText and warnings.

Parameters

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

JSON fields

Example: a real response for the white shoe photo in the request above, with category=sneaker. The text can differ on every call and is a draft.

{
  "title": "Beyaz Kanvas Dokulu Bağcıklı Sneaker Ayakkabı",
  "description": "Bu beyaz sneaker, sade ve yalın tasarımıyla günlük stilinizin temel parçalarından biri olmaya adaydır. Kanvas dokulu dış yüzeyi ve aynı tondaki dikiş detaylarıyla temiz bir görünüm sunan bu ayakkabı, her türlü kıyafetle kolayca uyum sağlar. Bağcıklı kapanış sistemi, ayak yapınıza göre ayarlanabilen bir yapı sunarken, ayakkabının genelindeki beyaz renk bütünlüğü modern bir estetik yaratır. Metal halkalı bağcık delikleri ve tonal bağcıklarıyla bütünüyle beyaz bir görünüm sergiler.\n\nGündelik kombinlerinizde kot pantolonlar, şortlar veya keten pantolonlarla bir araya getirerek zahmetsiz bir şıklık yakalayabilirsiniz. Sade tasarımı sayesinde hem spor hem de yarı resmi kıyafetlerle birlikte kullanılabilir. Ürünün burun kısmındaki dokulu kauçuk detay, tasarıma hareket katarken yan panellerdeki dikişler belirgin bir görünüm sergiler. Gardırobunuzdaki farklı renk ve desenlerle rahatça eşleştirebileceğiniz bu çok yönlü model, stilinize ferah bir dokunuş ekler.\n\nŞehir hayatının hareketli temposuna uyum sağlayan bu model, düşük bilekli yapısı ve klasik silüetiyle dikkat çeker. Taban kenarlarındaki ince çizgisel detaylar ve burun bölümündeki pütürlü doku, tasarımın yalınlığını destekleyen estetik unsurlardır. Farklı mekanlarda kullanıma uygun olan bu tasarım, nötr rengi sayesinde mevsim geçişlerinde de kurtarıcı bir parça rolü üstlenir. Minimalist detayları ve beyazın zamansız etkisini birleştiren bu ürünü, çeşitli aksesuarlarınızla kolayca tamamlayarak kendi tarzınızı yansıtabilirsiniz.",
  "features": ["Bağcıklı kapanış sistemi", "Kanvas dokulu dış yüzey", "Düşük bilekli tasarım", "Beyaz metal kuşgözü detayları", "Tonal dikiş özellikleri", "Dokulu burun koruması"],
  "color": "beyaz",
  "material": null,
  "keywords": ["beyaz sneaker", "kanvas ayakkabı", "bağcıklı sneaker", "günlük ayakkabı", "düz taban sneaker", "beyaz ayakkabı", "spor ayakkabı", "bez ayakkabı"],
  "altText": "Yan profilden görünen, beyaz renkli, kanvas dokulu ve beyaz bağcıklı düşük bilekli sneaker ayakkabı.",
  "warnings": []
}

Example

curl "https://theglitch.app/api/v1/listing-copy?url=https://theglitch.app/showcase/feat-bgrm-shoe-before.webp&category=sneaker" \
  -H "X-Api-Key: YOUR_API_KEY"

• The output is a draft: check details such as brand, size and material before you publish. Health claims and superiority claims such as "the best" or "flawless" are forbidden in the prompt; this is not a guarantee of legal compliance.
• brand and category are optional (60 characters max) and reach the model as data, not as instructions; control characters are stripped.
• color and material come back null when they are not visible in the photo (no guessing). The title is at most 100 characters and the alt text at most 125.
• For now it writes Turkish only.
• If the model cannot produce a result that matches the schema, it is retried once with a backup model; if that also fails you get 503 GPU_ERROR (Retry-After: 30) and no credits are charged.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

GET POST /v1/product-sceneAI · 2–7 credits

Creates an extra image for a marketplace listing from a product photo: a white background with a soft shadow (studio), the chosen lifestyle setting (lifestyle) or studio light that keeps the background (relight). The result is an image.

Parameters

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

Response

Example

curl "https://theglitch.app/api/v1/product-scene?url=https://theglitch.app/showcase/feat-bgrm-shoe-before.webp&sceneType=studio&aspectRatio=2:3" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o scene.webp

• Credits depend on the type: studio 2, lifestyle 7, relight 6 AI credits. Without sceneType, studio is charged.
• This is for extra images: the marketplace main image should stay the original white-background photo.
• In the studio and lifestyle types the product's original pixels are pasted back into the result when the placement check passes. If it fails, lifestyle retries with a backup model, while studio returns the raw output with the X-Glitch-Notice: product-redrawn header. If the backup fails the check too, the lifestyle result carries the same header.
• The relight type does not paste pixels back: the product is redrawn by AI, and lettering, logos and texture may change. Its output should not be used as the main image.
• No free-text prompt is accepted; the scene is chosen only through sceneType and scenePreset. Ideally send a photo with a single product: if no product can be separated from the background, you get 422 GPU_INPUT_REJECTED and no credits are charged.
• An invalid sceneType, scenePreset or aspectRatio value is rejected with 400 VALIDATION_ERROR before any AI call; no credits are charged. scenePreset is used only by the lifestyle type and is ignored by the others.

A successful call deducts from your monthly AI credits only; it does not count against the request quota. The cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. Which failed requests are charged is listed under Quotas & Limits. (If your request quota is exhausted, AI calls also return 429 REQUEST_QUOTA_EXCEEDED.)

Monthly request quotas depend on your plan. AI requests draw from a separate balance of AI credits, and every AI operation has a fixed credit cost. There is no per-minute rate limit. The quota period is your billing period on paid plans and the UTC calendar month on the Free plan (it resets on the 1st).

• A single request combining resize + 5 effects + format conversion = 1 request.
• AI endpoints deduct from your AI credits only; they do not count against the request quota. The credit cost depends on the operation: remove-bg, upscale, colorize, remove-object, ocr (per image) and listing-copy cost 1 credit; product-scene costs 2 (studio), 6 (relight) or 7 (lifestyle); face-restore, restore and headshot cost 9. vectorize (SVG) is not an AI operation and counts against the request quota. Current weights are in the aiUnits field of /api/v1/info, and the credits charged by a call in the X-Glitch-AI-Units header (sent only when credits were charged). If you have fewer credits left than the operation costs, the request returns 429 GPU_QUOTA_EXCEEDED without running; the body carries required, limit, used and resetsAt.
• Only successful responses count against the request quota; the one exception is vectorize, where a request refused after vectorizing has run (an output too detailed to serve) also counts as 1 request. For AI credits, a successful call deducts its weight, and so does a request that disconnects after the AI work was sent to the provider or fails after the AI step for a reason not on our side. A fault on the AI service, temporary throttling (GPU_BUSY), an image the model rejects (GPU_INPUT_REJECTED), 4xx validation errors and our own timeouts (408) deduct nothing.
• 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. Professional headshots, image to text, listing copy and SVG vectorization results are never cached: on those endpoints an identical request is processed again and counts again.
• When your request quota runs out, AI requests stop too: you get 429 REQUEST_QUOTA_EXCEEDED even if you still have AI credits left.

Responses include custom headers so you can monitor your usage:

Error responses are always JSON with a 4xx/5xx status code. Successful responses are binary images, except /image-info and /listing-copy (JSON), /ocr (JSON, text or a document, depending on output) and /vectorize (SVG). Tell success from failure by the status code, not the Content-Type.

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