API Documentation

Simple, powerful image processing. Get started in minutes.

curl -X POST https://www.mayapix.io/public/api/v1/images/process \
  -H "X-API-Key: YOUR_KEY.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "operations": [{"type": "compress", "preset": "mayaai"}]
  }'

🌟

Parameter Wizard

INTERACTIVE

Answer a few questions and get your perfect API call - no docs reading needed.

Step 1 of 4 0%

🔍 What kind of images are you processing?

Authentication

Include your API key in every request using one of these methods:

Header: X-API-Key: mpx_xxxxx.your_secret

Or: Authorization: Bearer mpx_xxxxx.your_secret

Important: Never share your API key. Create separate keys for each integration.

Limits & Policies

File Limits

Max file size: 20 MB
Max dimensions: 8000 x 8000 px
Formats: JPEG, PNG, WebP, GIF

Data Retention

Image storage: 7 days
Job records: 30 days
Usage logs: 90 days

Rate Limits by Plan

Plan	Requests/min	Monthly Images
Free	10	50
Starter	60	1,000
Pro	200	5,000
Business	500	20,000
Enterprise	Custom	Unlimited

⭐

MayaAI - Recommended

One call does everything. No tuning required.

Detects the subject, removes whitespace (and optionally the background), scales appropriately, adds breathing room, and outputs a compressed WebP. Start here, fall back to Advanced Operations only if you need precise control.

Defaults when you don't specify a param

Output size	Subject's natural size + 5% breathing room on each side
Canvas color	White `ffffff`
Output format	WebP. Override with `"format": "jpeg"` for legacy systems
BG removal	On by default. Set `"remove_bg": false` to disable. Free plan: silently skipped, no error.
Upscaling	Off by default. Auto-enabled when `size` is set. Override with `"upscale": false`

Core Parameters

Parameter	Default	Description
remove_bg	true	Remove background. Free plan: silently skipped (no error). Set `false` if BG is already clean
size	-	Force square canvas (e.g. `1000` → 1000×1000). Subject scales to fill. Omit for natural size output
background	ffffff	Canvas fill color (hex, no #) or `"transparent"` for alpha output - auto-outputs PNG
format	webp	Output format: `webp`, `jpeg`, `png`

Common Scenarios

// 1. Default - BG removal on, natural subject size + 5% breathing room
{"type": "mayaai"}

// 2. Catalog normalization - 1000×1000, subject fills canvas
{"type": "mayaai", "size": 1000}

// 3. Transparent cut-out PNG (no background at all)
{"type": "mayaai", "background": "transparent"}

// 4. Transparent cut-out, 1000×1000
{"type": "mayaai", "background": "transparent", "size": 1000}

// 5. Custom canvas color (light gray studio look)
{"type": "mayaai", "size": 1000, "background": "f5f5f5"}

// 6. Disable BG removal (image already has clean background)
{"type": "mayaai", "remove_bg": false}

Advanced MayaAI Parameters (most users never need these)

Parameter	Default	Description
upscale	auto	When `size` is set, defaults to `true` (fill canvas). Set `false` to center small subjects without scaling them up
padding	5	Breathing room as % of canvas each side (0–25). 5% = 50px on a 1000px canvas
model	isnet-general-use	BG removal model. See model guide below
width + height	-	Non-square canvas. e.g. `"width": 1200, "height": 628`. Overrides `size`
tolerance	20	How aggressively to detect solid backgrounds (0–100). Increase for off-white or gradient BGs

// size + upscale:false → fixed canvas, small subjects centered (not blown up)
{"type": "mayaai", "size": 1000, "upscale": false}

// Custom non-square canvas
{"type": "mayaai", "width": 1200, "height": 628}

// Tighter padding (2% each side)
{"type": "mayaai", "padding": 2}

// Maximum quality BG removal (slower)
{"type": "mayaai", "remove_bg": true, "model": "birefnet-general"}

// Product on off-white background - raise tolerance
{"type": "mayaai", "tolerance": 40}

How MayaAI Works

🔍

Tight-crop

Finds the subject bounding box and removes surrounding whitespace

📐

Scale

Scales to fit the canvas. No upscale by default; fills canvas when size is set

🖼

Pad

Centers subject on canvas with consistent breathing room on all sides

🤖

Smart compress

AI picks optimal WebP quality per image (60–90% smaller)

Runs entirely on our servers - no third-party APIs, no per-image fees passed to you, your images never leave our infrastructure.

Process Single Image

POST /api/v1/images/process

Request Body

Field	Type	Required	Description
image_url	string	Yes*	URL of image to process
image	string	Yes*	Base64 encoded image
operations	array	Yes	List of operations
webhook_url	string	No	Callback URL for completion

* One of image_url or image is required

Batch Processing

POST /api/v1/images/batch

Process multiple images in a single request.

{
  "images": [
    {
      "image_url": "https://example.com/photo1.jpg",
      "operations": [{"type": "compress", "preset": "mayaai"}]
    },
    {
      "image_url": "https://example.com/photo2.jpg",
      "operations": [{"type": "resize", "width": 800}]
    }
  ],
  "webhook_url": "https://yoursite.com/webhook"
}

Job Status & Download

GET /api/v1/jobs/{job_id}

Get job status and result details

GET /api/v1/jobs/{job_id}/download

Download the processed image file

Check Usage

GET /api/v1/usage

{
  "plan": "pro",
  "period": "2024-01",
  "images_processed": 1523,
  "monthly_limit": 5000,
  "remaining": 3477,
  "resets_at": "2024-02-01T00:00:00Z"
}

Compress

Reduce file size. Does not change dimensions (except presets that include a max size - see table).

Defaults: quality = 85, format = keeps original format

Parameter	Default	Description
quality	85	1–100. Lower = smaller file
format	original	`jpeg`, `png`, `webp`, `gif`. Omit to keep original format
preset	-	Pre-configured shortcut. Overrides quality + format. See table below

⚠️ What presets actually do - read before using

Preset	Format	Quality	Max Size	Notes
mayaai	WebP	AI-selected	No resize	Best for all images. Adapts per image
ecommerce	WebP	85	1200px	Scales DOWN if larger than 1200px
thumbnail	WebP	75	300px	Scales DOWN to max 300px
highquality	PNG	95	2400px	Scales DOWN to max 2400px
social	JPEG	80	1200×630	Cover-crops to 1200×630. Pair with resize first
mobile	WebP	70	640px	Scales DOWN to max 640px
catalog	WebP	80	800px	Scales DOWN to max 800px

// AI picks quality, outputs WebP, no resize
{"type": "compress", "preset": "mayaai"}

// Custom quality, convert to WebP
{"type": "compress", "quality": 75, "format": "webp"}

// Custom quality, keep original format (omit format param)
{"type": "compress", "quality": 80}

Resize

Change dimensions. Does not crop - use crop for that.

Defaults: fit = contain, upscale = false (small images stay small)

Parameter	Default	Description
width	-	Target width (1–8000)
height	-	Target height (1–8000)
fit	contain	How to handle aspect ratio. See fit modes below
background	ffffff	Fill color for `contain` / `fill` padding
upscale	false	Allow enlarging images smaller than target

Fit Modes

Mode	Behavior	Distorts?	Crops?
contain	Fits inside box, adds padding if needed	No	No
cover	Fills box completely, crops overflow	No	Yes
fill	Fills box with padding around content	No	No
max	Scales down to max dimension, keeps aspect	No	No
stretch	Forces exact dimensions	Yes	No

// Scale down to max 800px wide (default: no upscale, keeps aspect ratio)
{"type": "resize", "width": 800}

// Fit inside 1000×1000 box with white padding (no crop, no distort)
{"type": "resize", "width": 1000, "height": 1000, "fit": "contain", "background": "ffffff"}

// Fill 800×600, crop overflow (good for hero images / covers)
{"type": "resize", "width": 800, "height": 600, "fit": "cover"}

// Allow upscaling small images
{"type": "resize", "width": 1200, "upscale": true}

Crop Operation

Cut out a portion of the image, or use smart_pad mode to auto-detect the product and center it with consistent margins.

Standard Crop

Parameter	Type	Description
width	int	Crop width
height	int	Crop height
position	string	Where to crop from: `center`, `top-left`, `top-right`, etc. Default: `center`
x, y	int	Exact pixel start position
aspect_ratio	string	e.g. `"1:1"`, `"16:9"` - crops to ratio

{"type": "crop", "width": 500, "height": 500, "position": "center"}
{"type": "crop", "width": 300, "height": 300, "x": 100, "y": 50}
{"type": "crop", "aspect_ratio": "1:1"}

Smart Pad New

Auto-detects the product bounding box, trims the background, and re-pads with a consistent margin on all sides. Perfect for uniform product grids.

Parameter	Type	Default	Description
mode	string	-	Set to `"smart_pad"` to enable
padding	float	10	Margin as % of content size on each side (0–50)
background	string	auto	Background hex color e.g. `"ffffff"`. Auto-detected from corners if omitted
tolerance	int	20	Color distance threshold (0–100). Increase for noisy/gradient backgrounds
width, height	int	-	Optional output size after padding (keeps aspect ratio)

// Auto-detect background, 10% margin, resize to 800×800
{"type": "crop", "mode": "smart_pad", "padding": 10, "width": 800, "height": 800}

// Explicit white background, tighter margin
{"type": "crop", "mode": "smart_pad", "background": "ffffff", "padding": 5, "tolerance": 15}

// Off-white / gradient background (raise tolerance)
{"type": "crop", "mode": "smart_pad", "padding": 10, "tolerance": 40}

Remove Background

Local AI background removal powered by rembg. Creates transparent PNG. Choose from 8 models for different use cases.

🎯 Local AI, Not Remove.bg

Runs entirely on our servers - no per-image API fees. Same quality as paid services at a fraction of the cost.

Plan Required: Starter and above. GIF images are not supported.

Parameters

Parameter	Type	Default	Description
type	string	-	`"remove_background"` (required)
model	string	`isnet-general-use`	AI model to use (see table below)

Model Options

Model	Best For	Speed	Quality
isnet-general-use	Default - products, objects, general use	Fast	★★★★
u2net	Solid backgrounds, legacy	Fast	★★★
u2netp	Speed-critical use cases	Fastest	★★
silueta	Fast silhouettes	Fast	★★★
u2net_human_seg	People, portraits	Fast	★★★★
u2net_cloth_seg	Clothing items	Fast	★★★
isnet-anime	Anime, illustrations	Fast	★★★★
birefnet-general	Hair, glass, fur - maximum quality	Slow	★★★★★

Examples

// Default (best balance)
{"type": "remove_background"}

// Maximum quality for complex subjects (hair, fur, glass)
{"type": "remove_background", "model": "birefnet-general"}

// Optimized for human portraits
{"type": "remove_background", "model": "u2net_human_seg"}

// ⭐ Recommended: MayaAI all-in-one (bg removal + resize + compress in one call)
{"type": "mayaai", "remove_bg": true, "background": "ffffff"}

// Manual pipeline: remove background then compress
{
  "image_url": "https://example.com/product.jpg",
  "operations": [
    {"type": "remove_background"},
    {"type": "compress", "preset": "ecommerce"}
  ]
}

Recipes

Ready-made operation chains for common use cases. Copy, paste, send.

🛒 E-commerce (Full pipeline - one call)

BG removal + 1000×1000 white canvas + WebP. BG removal is on by default.

{"image_url": "...", "operations": [{"type": "mayaai", "size": 1000}]}

🧥 Fashion / Clothing (Clothing-specific model)

Use model: u2net_cloth_seg for cleaner cuts on fabric edges. MayaAI handles the rest.

{"image_url": "...", "operations": [{"type": "mayaai", "model": "u2net_cloth_seg", "size": 1000}]}

📱 Social Media (Instagram / LinkedIn)

Square 1080×1080, center-cropped, JPEG

{"image_url": "...", "operations": [
  {"type": "resize", "width": 1080, "height": 1080, "fit": "cover"},
  {"type": "compress", "quality": 85, "format": "jpeg"}
]}

🖼 Blog / Article Hero

1200×630 for Open Graph / social preview

{"image_url": "...", "operations": [
  {"type": "resize", "width": 1200, "height": 630, "fit": "cover"},
  {"type": "compress", "quality": 85, "format": "webp"}
]}

🗜 Just Compress (no resize, no format change)

Reduce file size only, keep everything else

{"image_url": "...", "operations": [{"type": "compress", "quality": 80}]}

🎯 High-quality Cut-out (hair, glass, fur)

birefnet-general is the highest quality model (slower). background: transparent preserves the alpha channel as PNG.

{"image_url": "...", "operations": [{"type": "mayaai", "model": "birefnet-general", "background": "transparent"}]}

Webhooks

Two ways to receive job notifications - pick the one that fits your workflow.

Method 1: Ad-hoc `webhook_url`

Pass a URL directly in the process request. Simple, one-time, no setup needed. No HMAC signing.

{
  "image_url": "https://example.com/photo.jpg",
  "operations": [{"type": "mayaai"}],
  "webhook_url": "https://your-site.com/hook"
}

Method 2: Registered Webhooks (CRUD)

Register a persistent endpoint that fires for all matching jobs. HMAC-signed, supports event filtering, auto-disables after 10 consecutive failures.

GET /api/v1/webhooks - list all registered webhooks

POST /api/v1/webhooks - register a new webhook

PUT /api/v1/webhooks/{id} - update url, events, or active state

POST /api/v1/webhooks/{id}/test - send a test ping to verify your endpoint

POST /api/v1/webhooks/{id}/regenerate-secret - rotate HMAC signing secret

DELETE /api/v1/webhooks/{id} - remove a webhook (max 10 per account)

Events

job.completed job.failed batch.completed

Verifying the signature

Each registered webhook delivery includes an X-MayaPix-Signature header. Verify it to confirm the request came from MayaPix.

// PHP example
$signature = hash_hmac('sha256', json_encode($payload), $webhookSecret);
if (!hash_equals($signature, $request->header('X-MayaPix-Signature'))) {
    abort(401);
}

Payload format

{
  "event": "job.completed",
  "job_id": "550e8400-e29b-41d4...",
  "status": "completed",
  "result": {
    "download_url": "https://...",
    "size": 245760,
    "width": 1600,
    "height": 1200
  }
}

Error Codes

Code	Meaning
200	Success
202	Job queued (processing)
400	Bad request - check parameters
401	Invalid API key
402	Quota exceeded - upgrade plan
403	Feature not on your plan
404	Job not found
429	Rate limit - slow down
500	Server error - contact support

Need Help?

Email us at support@mayapix.io

Get Your API Key