#Image Delivery API

Pixault serves transformed images through a URL-based API. Every transformation is encoded directly in the URL path, making images fully cacheable at the CDN edge.

#URL Pattern

https://img.pixault.io/{project}/{imageId}/{transformations}.{format}

#Transformation Parameters

#Fit Modes

#Examples

#Basic Resize

# 800px wide, auto height, WebP
https://img.pixault.io/myapp/img_01JK/w_800.webp
# 200x200 thumbnail, cover crop
https://img.pixault.io/myapp/img_01JK/w_200,h_200,fit_cover.webp

#Quality Control

# High quality for print
https://img.pixault.io/myapp/img_01JK/w_1200,q_95.jpg
# Compressed for mobile
https://img.pixault.io/myapp/img_01JK/w_400,q_60.webp

#Low-Quality Image Placeholder (LQIP)

Generate tiny blurred placeholders for progressive image loading:

https://img.pixault.io/myapp/img_01JK/w_40,q_20,blur_10.webp

Use this as a background-image while the full image loads.

#Watermarking

# Bottom-right watermark at 40% opacity
https://img.pixault.io/myapp/img_01JK/w_1200,wm_logo,wm_pos_br,wm_opacity_40.jpg
# Tiled watermark across entire image
https://img.pixault.io/myapp/img_01JK/w_1200,wm_copyright,wm_pos_tile,wm_opacity_20.jpg

#Named Transforms

Apply preconfigured transform presets:

# Apply the "gallery" transform
https://img.pixault.io/myapp/img_01JK/t_gallery.webp
# Named transform with overrides
https://img.pixault.io/myapp/img_01JK/t_gallery,w_400.webp

See Named Transforms for creating presets.

#Plugin Transforms

If you have marketplace plugins activated, invoke them by adding the plugin prefix to the transformation parameters:

# Background removal
https://img.pixault.io/myapp/img_01JK/w_800,bg_remove.png
# Smart crop (face-aware)
https://img.pixault.io/myapp/img_01JK/w_400,h_400,smart_crop_face.webp
# Sepia filter
https://img.pixault.io/myapp/img_01JK/w_800,filter_sepia.webp
# Watermark template (copyright)
https://img.pixault.io/myapp/img_01JK/w_1200,wt_copyright.jpg
# Combine multiple plugins
https://img.pixault.io/myapp/img_01JK/w_800,bg_remove,filter_vibrance,wt_copyright.png

See Plugin Marketplace API for the full list of available plugins and their parameters.

#Embed Tags

GET /api/{project}/{imageId}/embed

Generate responsive HTML embed tags with srcset, <picture> elements, and Schema.org JSON-LD — ready to paste into your pages.

#Query Parameters

#Examples

# Get a <picture> element with AVIF/WebP sources
curl "https://img.pixault.io/api/myapp/img_01JKXYZ/embed" \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"
# Custom breakpoints and CSS class
curl "https://img.pixault.io/api/myapp/img_01JKXYZ/embed?widths=320,640,1024&cssclass=hero-img"
# Get as simple <img> tag with srcset
curl "https://img.pixault.io/api/myapp/img_01JKXYZ/embed?format=img"
# Get raw JSON for custom rendering
curl "https://img.pixault.io/api/myapp/img_01JKXYZ/embed?format=json"

#Response — format=picture (default)

{
  "html": "<picture><source srcset=\"...\" type=\"image/avif\"><source srcset=\"...\" type=\"image/webp\"><img src=\"...\" alt=\"...\" width=\"4000\" height=\"3000\" loading=\"lazy\"></picture>",
  "jsonLd": { "@context": "https://schema.org", "@type": "ImageObject", "..." }
}

#Response — format=json

{
  "src": "https://img.pixault.io/myapp/img_01JKXYZ/w_1200.auto",
  "srcset": "https://img.pixault.io/myapp/img_01JKXYZ/w_400.auto 400w, ... 1200w",
  "sources": [
    { "srcset": "...w_400.avif 400w, ...", "type": "image/avif" },
    { "srcset": "...w_400.webp 400w, ...", "type": "image/webp" }
  ],
  "alt": "Mountain landscape at sunset",
  "width": 4000,
  "height": 3000,
  "sizes": "100vw",
  "jsonLd": { }
}

Use the json format to build custom <picture> or <img> elements in your framework of choice.

#Signed URLs

For original file downloads, Pixault supports HMAC-SHA256 signed URLs:

https://img.pixault.io/myapp/img_01JK/original.jpg?sig=abc123def&exp=1709312400

The signature is computed over {project}/{imageId}/original.{format}?exp={timestamp} using your account's HMAC secret.

#Response Headers

#Format Negotiation

If the Accept header includes image/webp or image/avif, Pixault will automatically select the most efficient format when the URL extension is omitted. Explicit format extensions always take precedence.

#Rate Limits

Delivery endpoints use per-project sliding window rate limiting:

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

#Error Responses

All errors follow RFC 7807 ProblemDetails format:

{
  "type": "https://httpstatuses.io/404",
  "title": "Not Found",
  "detail": "Image 'img_01JKXYZ' not found in project 'myapp'.",
  "status": 404
}