API Documentation

Simple, powerful image processing. Get started in minutes.

curl -X POST https://mail.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	none	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. Use `"auto"` for smart detection. See model guide below
width + height	none	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
face_center	false	Detect faces/models and bias subject placement toward the canvas center
target_size_kb	300	Target output size for smart compression (10–5000 KB)
quality_floor	70	Minimum quality % for smart compression (1–100)
skip_compressed_threshold	disabled	Skip images already compressed below this bytes-per-pixel value (e.g., `0.3`). Useful for bulk syncs. `0` or omitted = disabled
watermark	false	Add a brand watermark
watermark_text	none	Text watermark when `watermark` is true
watermark_image_url	none	Logo URL watermark when `watermark` is true and text is empty

// 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}

// Smart mode: auto-detect model, padding, and background
{"type": "mayaai", "smart": true}

// Auto-detect only the background removal model
{"type": "mayaai", "model": "auto"}

When smart: true or model: "auto" is set, MayaAI analyzes the image and picks defaults for the subject. Any explicit parameter you provide still overrides the smart defaults.

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

Base64 Example

{
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...",
  "operations": [
    {"type": "mayaai", "size": 1000}
  ]
}

The image field accepts a raw base64 string or a data URI (data:image/png;base64,...). Max 20 MB after decoding.

Defaults at a Glance

If you omit a parameter, these values are used:

Parameter	Default	Notes
format	`webp`	`compress` keeps the original format unless you specify one
remove_bg	`true`	Silently skipped on the Free plan
model	`isnet-general-use`	Use `"auto"` for smart detection
background	`ffffff`	White canvas. Use `"transparent"` for PNG with alpha
padding	`5`	5% of canvas on each side
target_size_kb	`300`	MayaAI smart compression target
quality_floor	`70`	MayaAI never compresses below this
fit	`contain`	Resize preserves aspect ratio
upscale	`false`	Small images are not enlarged unless requested
position	`center`	Standard crop starts from center
watermark	`false`	No watermark unless enabled

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	none	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	none	Target width (1–8000). Provide at least one dimension
height	none	Target height (1–8000). Provide at least one dimension
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	Default	Description
width	int	none	Crop width
height	int	none	Crop height
position	string	center	Where to crop from: `center`, `top-left`, `top-right`, etc.
x, y	int	none	Exact pixel start position
aspect_ratio	string	none	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	required	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	none	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	required	`"remove_background"`
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"}]}

Salla Embedded Integration

Endpoints used by the Salla embedded app. Include the Salla token in the Authorization: Bearer <salla_token> header.

Get Store Settings

GET /api/v1/integrations/salla/settings

Returns the merchant's saved settings, store info, Salla subscription status, and the linked MayaPix plan/usage (monthly remaining images).

The response includes both the Salla billing cycle (subscription.ends_at) and the calendar-month quota reset (usage.resets_at).

Save Store Settings

POST /api/v1/integrations/salla/settings

Save the embedded app settings. Example body:

{
  "settings": {
    "auto_process": true,
    "bg_removal": true,
    "bg_model": "isnet-general-use",
    "canvas_size": "1:1",
    "canvas_width": null,
    "canvas_height": null,
    "output_format": "webp",
    "compression_quality": 85,
    "padding_color": "#FFFFFF",
    "padding": 5,
    "smart_quality": true,
    "target_size_kb": 300,
    "quality_floor": 70,
    "skip_compressed_threshold": 0,
    "face_center": false,
    "watermark": false,
    "watermark_text": "",
    "keep_original": false
  }
}

Canvas size: choose "1:1", "4:3", "16:9", "original", or "custom". For custom, set canvas_width and canvas_height to positive pixel values.

Keep originals: when enabled, a backup of every original image is stored in the originals/ path for 7 days. Restore is manual only; there is no automatic restore endpoint.

Background model: bg_model sets the AI model used when bg_removal is true. Options: isnet-general-use (default), u2net_cloth_seg (fashion), u2net_human_seg (people), birefnet-general (best quality, slower).

Recommend Settings with AI

POST /api/v1/integrations/salla/recommend-settings

Upload 1-5 sample product images and receive a recommended preset and settings tuned for your store.

curl -X POST https://mail.mayapix.io/public/api/v1/integrations/salla/recommend-settings \
  -H "Authorization: Bearer <salla_token>" \
  -F "images[]=@product1.jpg" \
  -F "images[]=@product2.jpg"

Subscription Webhooks

POST /api/v1/webhooks/salla

Salla sends subscription events to this endpoint. MayaPix keeps the linked plan in sync automatically.

app.subscription.started app.subscription.renewed app.subscription.canceled app.subscription.expired app.trial.started app.trial.canceled app.trial.expired

Plan names are mapped to MayaPix slugs via config/services.salla.plan_map. Unknown names fall back to free.

Upload Brand Logo

POST /api/v1/integrations/salla/logo

Upload a brand logo for watermark. Send as multipart/form-data with a logo file (PNG/JPEG/WebP, max 2MB).

curl -X POST https://mail.mayapix.io/public/api/v1/integrations/salla/logo \
  -H "Authorization: Bearer <salla_token>" \
  -F "logo=@logo.png"

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?

Need help? Contact our support team.

Get Your API Key