CDN Usage
Using Pixelflare is simple! After uploading an image, you'll see it's direct URL as well as embed snippets for which you can copy and use.
Pixelflare also supports requesting images in different sizes, formats as well as applying on-the-fly edits/custom transformations. The UI will help you here, letting you choose the options you want, and giving your the complete URL. This page documents all the options available to you.
Original Image
By default, images are served at: https://pixelflare.cc/{owner}/{album}/{filename}
As well as a short URL of: https://pixelflare.cc/i/{image-id}
If you have a custom domain configured (e.g. you.example.com) then you can request your images from there. The only difference is that the {owner} (for full path) or the /i/ (for short URL) is no longer required. So, the format will be https://you.example.com/{album}/{filename} or https://you.example.com/{image-id}
Examples
- Basic: https://pixelflare.cc/alicia/pics/dino
- Short ID: https://pixelflare.cc/i/i777nn
- Custom domain, path: http://cdn.as93.net/pics/dino
- Custom domain, ID: http://cdn.as93.net/i777nn
Preset Variants
Requesting a resized / smaller image saves bandwidth and speeds up your site. We've got a series of preset variants which you can use.
On the public instance, the preset variants are: w128, w256, w512, w1024, w1536, w2048, thumb, og-image
To use these, simply append the variant to the end of the image URL, such that the format would be like https://pixelflare.cc/{owner}/{album}/{filename}/{variant} or https://pixelflare.cc/i/{image-id}/{variant}
Examples:
- 512px width, using full image path: https://pixelflare.cc/alicia/pics/dino.jpg/w512
- Thumbnail preview, requested via short ID: https://pixelflare.cc/i/i777nn/thumb
- Using custom domain, for width of 1024px: http://cdn.as93.net/pics/dino.jpg/w1024
- And, short ID on custom domain for 128px image: http://cdn.as93.net/i777nn/w128
Variant Details
| Variant | Dimensions | Use Case |
|---|---|---|
original | Full size | Default / original image |
w128 | 128px width | Tiny preview |
w256 | 256px width | Small thumbnail |
w512 | 512px width | Medium size |
w1024 | 1024px width | Large display |
w1536 | 1536px width | Extra large |
w2048 | 2048px width | Very large |
thumb | 128×128 | Square thumbnail (cropped) |
og-image | 1200×630 | Social media card (cropped) |
Format Conversion
Modern formats like WebP and AVIF can be significantly more efficient. Pixelflare supports on-the-fly format conversion.
Requesting an image in a specific format is easy, just add or modify it's file extension. You can use webp, avif and jpg
Examples:
- https://pixelflare.cc/alicia/pics/dino.jpg
- https://pixelflare.cc/i/i777nn.webp
- http://cdn.as93.net/pics/dino.jpg
- http://cdn.as93.net/i777nn.avif
You can also request both a specific size and format:
- https://pixelflare.cc/alicia/pics/dino.webp/w512
- https://pixelflare.cc/i/i777nn.avif/thumb
- http://cdn.as93.net/pics/dino.jpg/w1024
Note that there are a few caveats, outlined in the Limitations section at the end, however these will always be handled gracefully so that there won't ever be a situation where an image is never returned.
Advanced Transformations
The preset sizes and format conversions should cover off most use cases. But when precises control is needed, Pixelflare supports advanced transformations via URL query parameters. These enable you to request specific dimensions, quality, cropping as well as visual effects and modifications such as removing the background and cropping out extra whitespace around a subject.
Example:
Available Parameters
| Parameter | Description | Values |
|---|---|---|
| Format & Quality | ||
Format (f=) | Output image format. Auto negotiates based on browser support. | auto, avif, webp, jpeg, baseline-jpeg, png (default: auto) |
Quality (q=) | Compression quality. Higher values mean better quality but larger file size. | 1-100 (default: 85) |
| Dimensions & Fit | ||
Width (w=) | Target width in pixels. Omit to maintain aspect ratio. | 1-4096 (default: original) |
Height (h=) | Target height in pixels. Omit to maintain aspect ratio. | 1-4096 (default: original) |
Fit Mode (fit=) | How the image should be resized. Options: scale-down (shrink only, never enlarge), contain (fit within, may letterbox), cover (fill completely, may crop), crop (like cover with gravity), pad (fit with padding), squeeze (exact size, may distort). | scale-down, contain, cover, crop, pad, squeeze (default: scale-down) |
| Cropping & Position | ||
Gravity (g=) | Focus point for cropping. Face detection automatically focuses on detected faces. | auto, center, face, top, bottom, left, right (default: auto) |
Trim (trim=) | Crop specific pixels from edges. Format: top:N,left:N,right:N,bottom:N. Max 1000px per side. | Example: top:10,left:20,right:20,bottom:10 (default: none) |
| Color & Effects | ||
Blur (blur=) | Apply Gaussian blur. Higher values create more blur. | 1-250 (default: none) |
Sharpen (sharpen=) | Sharpen the image. Higher values increase sharpness. | 0-10 (default: 0) |
Brightness (br=) | Adjust brightness. 1.0 is normal, below darkens, above brightens. | 0.5-2.0 (default: 1.0) |
Contrast (co=) | Adjust contrast. 1.0 is normal, below reduces, above increases. | 0.5-2.0 (default: 1.0) |
Saturation (sat=) | Adjust color saturation. 0 is grayscale, 1.0 is normal, 2.0 is vivid. | 0-2.0 (default: 1.0) |
Gamma (gam=) | Adjust gamma correction. Below 1.0 darkens, above 1.0 brightens midtones. | 0.5-2.0 (default: 1.0) |
| Rotation & Flip | ||
Rotation (r=) | Rotate the image clockwise by the specified degrees. | 0, 90, 180, 270 (default: 0) |
Flip (flip=) | Mirror the image. h=horizontal, v=vertical, hv=both. | h, v, hv (default: none) |
| Background & Metadata | ||
Background Removal (segment=) | AI-powered background removal. Creates transparency (use with PNG/WebP formats). | foreground (default: disabled) |
Background Color (bg=) | Fill transparent areas or padding with this color. 6-digit hex without #. | Example: ffffff (white), 000000 (black) (default: transparent) |
Metadata (meta=) | Control whether EXIF metadata is preserved in the output image. | none, copyright, keep (default: none) |
Tips
- Set
f=autoto enable automatic format negotiation based on browser support (serves AVIF to modern browsers, WebP as fallback) - Use
g=faceorg=autofor smart cropping that detects faces or important areas - Combine
segment=foregroundwithf=pngorf=webpfor AI background removal with transparency - All numeric parameters are auto-clamped to their valid ranges (values outside the range are adjusted, not rejected)
Best Practices
- Use preset variants (
w512,w1024) instead of custom transforms when possible - Request WebP or AVIF for modern browsers
- Use
q=80-85for most use cases the quality difference is imperceptible - For responsive images, use multiple variants with
srcset
Responsive image example:
<img
src="https://pixelflare.cc/alicia/pics/photo.jpg/w512"
srcset="
https://pixelflare.cc/alicia/pics/photo.jpg/w512 512w,
https://pixelflare.cc/alicia/pics/photo.jpg/w1024 1024w,
https://pixelflare.cc/alicia/pics/photo.jpg/w2048 2048w
"
sizes="(max-width: 768px) 512px, 1024px"
alt="Photo description"
/>How it works
For a deep dive into how images are served, cached, converted and transformed, see the technical documentation.
At a high-level, when you sign up for a Pixelflare account, we create you a dedicated place in our R2 bucket where your original images will be stored. We never modify the original images.
We then have a gateway where all requests go through (no matter weather it's a short ID, using your custom domain or the images full path). When a request comes in, we first check if there's already a cached version of that image, and if so we respond with that cached image. Otherwise, we go and find the original image, and apply any transformations (resizing, converting, etc) and then respond with that image, while also caching it for next time.
When no size, format or custom transformations are specified, we support smart negotiation, whereby we serve the most optimal supported format, size and variant based on what is supported by the end user's browser and device. So, for example, if the requested image in a WebP, but and the client doesn't support WebP, then we'll serve it in the next best supported format. Likewise if requested image is large and the end user is on a very slow connection, we respond with a lower quality version in the interim. If you don't want smart content negotiation, you can disable it by simply requesting a specific variant or format.
Limitations
- Converting non-PNG images into PNG format is not supported
- Images over 1,200px (longest side) cannot be converted into AVIF
- Large images (>12,000px or >70MB) cannot be converted or processed at all
- GIF and WebP animations will have their total animation frames limited to 50 megapixels
- SVG files will not be resized (there's no need!), they will just be sanitized and optimized
- Encrypted images cannot be resized, converted or transformed (for security reasons), nor will they be cached
- Custom transformations (using URL GET parameters) are only available to paid users, and are limited to 100 cached variants per image
- If custom transformations AND preset size and/or file extensions is present, then the custom transformations will take precedence
- First time requests might be slower, but once transformed, all subsequent requests will be served form an edge cache and will be fast!
Note that when a format conversion, transformation or other operation fails, we serve either the original image or fallback to the most performant and compatible lossless version. So there should never be an instance where no image is returned at all, even if you request an impossible or unsupported transformation.