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

#Delivery by publicId

Every image also has a publicId — a human-readable slug you choose (e.g. sunset-over-tahoe) — that you can use in delivery URLs in place of the opaque imageId. This gives you clean, memorable, SEO-friendly URLs.

# By publicId (pretty URL)
https://img.pixault.io/{project}/{publicId}.{format}
# By publicId, with transformations
https://img.pixault.io/{project}/{transformations}/{publicId}.{format}
                              

#Examples

# Identity — auto format via Accept negotiation
https://img.pixault.io/myapp/sunset-over-tahoe.auto
# 800px wide, WebP
https://img.pixault.io/myapp/w_800/sunset-over-tahoe.webp
# Named transform with an override
https://img.pixault.io/myapp/t_gallery,w_400/sunset-over-tahoe.auto
                              

Transform order differs from imageId URLs. With a publicId the transformations come first (/{project}/{transformations}/{publicId}), following the Cloudinary convention. With an imageId they come after (/{project}/{imageId}/{transformations}). Pixault tells the two apart automatically: the first path segment after the project is an imageId when it starts with img_, vid_, or eps_; otherwise it is treated as a transformation spec.

#The .auto format

.auto is the default format for publicId URLs. Pixault negotiates the most efficient format from the request's Accept header — AVIF or WebP where supported, falling back otherwise — and the response carries Vary: Accept. Use an explicit extension (.webp, .jpg) to pin a format instead.

#Setting a publicId

• On upload — pass a publicId, or let Pixault derive one from the image name. Slugs are lowercased and hyphenated, and may not begin with the reserved img_, vid_, or eps_ prefixes.

• Overwrite — upload with overwrite: true to replace whatever image currently holds a publicId. Without it, uploading to an existing publicId yields a uniquely-suffixed slug (e.g. sunset-over-tahoe-2), so an existing URL is never clobbered.

#Backward compatibility

publicId URLs are purely additive. Every existing imageId URL keeps working exactly as before, and existing /{project}/{filename} links still 302-redirect to the original. The publicId grammar only occupies URL shapes that previously returned 404, so enabling it can never change how an existing URL behaves.

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