#Plugin Marketplace API

Pixault's plugin marketplace extends the image processing pipeline with additional capabilities like background removal, smart cropping, image filters, and watermark templates. Plugins run as stages in the transformation pipeline and are billed per invocation.

#How Plugins Work

Plugins hook into three stages of the image processing pipeline:

Request → Parse → Resolve Named Transform
    → [PreProcess plugins]      ← e.g., background removal
    → Resize/Fit
    → [PostResize plugins]      ← e.g., smart crop
    → Blur / Watermark
    → [PostProcess plugins]     ← e.g., filters, watermark templates
    → Encode → Cache → Respond

A plugin only executes when:

1. It is activated for your project

2. It is invoked in the URL via its prefix

#Available Plugins

#Using Plugins in URLs

Plugins are invoked by adding their URL prefix to the transformation parameters:

https://img.pixault.io/{project}/{imageId}/{transforms},{plugin_prefix}_{value}.{format}

#Background Removal

Remove uniform backgrounds and replace with transparency:

# Auto-detect and remove background
https://img.pixault.io/myapp/img_01JK/w_800,bg_remove.png
# Custom sensitivity threshold (1-255, lower = more aggressive)
https://img.pixault.io/myapp/img_01JK/w_800,bg_50.png

#Smart Crop

Content-aware cropping that keeps the most important part of the image:

# Face-aware crop (skin-tone detection)
https://img.pixault.io/myapp/img_01JK/w_400,h_400,smart_crop_face.webp
# Entropy-based crop (highest detail region)
https://img.pixault.io/myapp/img_01JK/w_400,h_400,smart_crop_entropy.webp
# Center-weighted crop (default)
https://img.pixault.io/myapp/img_01JK/w_400,h_400,smart_crop_center.webp

#Image Filters

Apply Instagram-style effects using color matrices:

# Sepia tone
https://img.pixault.io/myapp/img_01JK/w_800,filter_sepia.webp
# Grayscale
https://img.pixault.io/myapp/img_01JK/w_800,filter_grayscale.webp
# Boosted saturation
https://img.pixault.io/myapp/img_01JK/w_800,filter_vibrance.webp
# Increased contrast
https://img.pixault.io/myapp/img_01JK/w_800,filter_contrast.webp
# Vignette (radial darkening)
https://img.pixault.io/myapp/img_01JK/w_800,filter_vignette.webp
# Warm tone (boost reds)
https://img.pixault.io/myapp/img_01JK/w_800,filter_warm.webp
# Cool tone (boost blues)
https://img.pixault.io/myapp/img_01JK/w_800,filter_cool.webp

#Watermark Templates

Dynamic text watermark overlays:

# Copyright notice (auto-generates year)
https://img.pixault.io/myapp/img_01JK/w_1200,wt_copyright.jpg
# Photographer credit
https://img.pixault.io/myapp/img_01JK/w_1200,wt_photographer.jpg
# Date stamp
https://img.pixault.io/myapp/img_01JK/w_1200,wt_date.jpg
# Date and time stamp
https://img.pixault.io/myapp/img_01JK/w_1200,wt_datetime.jpg
# Custom text (use + for spaces)
https://img.pixault.io/myapp/img_01JK/w_1200,wt_John+Smith+Photography.jpg

#Combining Plugins

Multiple plugins can be applied in a single request. They execute in pipeline order regardless of URL position:

# Remove background, apply sepia filter, add copyright
https://img.pixault.io/myapp/img_01JK/w_800,bg_remove,filter_sepia,wt_copyright.png

#Plugin Management API

#List All Plugins

GET /api/plugins

Returns all available marketplace plugins:

[
  {
    "name": "bg",
    "displayName": "Background Removal",
    "description": "AI-powered background removal...",
    "category": "Enhancement",
    "vendor": "PixaultLabs",
    "stage": "PreProcess",
    "priceCentsPerInvocation": 5,
    "urlPrefix": "bg",
    "parameters": [
      {
        "key": "value",
        "description": "Mode: 'remove' or numeric threshold (1-255)",
        "required": false,
        "defaultValue": "remove"
      }
    ]
  }
]

#Get Plugin Details

GET /api/plugins/{name}

Returns a single plugin descriptor or 404 if not found.

#List Project Plugins

GET /api/{project}/plugins

Returns plugins with activation status for your project:

[
  {
    "name": "bg",
    "displayName": "Background Removal",
    "description": "AI-powered background removal...",
    "category": "Enhancement",
    "vendor": "PixaultLabs",
    "stage": "PreProcess",
    "priceCentsPerInvocation": 5,
    "urlPrefix": "bg",
    "isActivated": true
  }
]

#Activate a Plugin

POST /api/{project}/plugins/{name}/activate

{
  "name": "bg",
  "status": "activated"
}

#Deactivate a Plugin

POST /api/{project}/plugins/{name}/deactivate

{
  "name": "bg",
  "status": "deactivated"
}

#Plugin Billing

Plugin invocations are tracked per use and billed as line items on your monthly invoice. The per-use price is set by the plugin vendor and shown in the marketplace listing.

Plugin costs are separate from your plan's bandwidth and storage billing.

#Error Responses

Invoking a plugin that is not activated for your project returns:

{
  "type": "https://httpstatuses.io/400",
  "title": "Bad Request",
  "detail": "Plugin 'bg' is not activated for project 'myapp'. Activate it via POST /api/myapp/plugins/bg/activate.",
  "status": 400
}