Accessing your images

URL Format

http://{user_id}.pixelcrush.io/{image_url}

{image_url} can be without http(s):// for better URL;, in that case it will always be fetched using http.

Also can be urlencoded in case the URL has parameters that conflicts with our parameters.


Valid Examples

http://{user_id}.pixelcrush.io/docs.pixelcrush.io/img/demo1.jpg?oneparameter=ok
http://{user_id}.pixelcrush.io/https://3n14nr.pixelcrush.io/docs.pixelcrush.io/img/demo1.jpg?oneparameter=ok

http://{user_id}.pixelcrush.io/docs.pixelcrush.io%2Fimg%2Fdemo1.jpg%3Foneparameter%3Dok
http://{user_id}.pixelcrush.io/http%3A%2F%2Fdocs.pixelcrush.io%2Fimg%2Fdemo1.jpg%3Foneparameter%3Dok

Accessing other resources

pixelcrush.io is, at its core, a CDN so we have, for your convenience, a proxy endpoint for your non image resources.

http://{user_id}.pixelcrush.io/cdn/{resource_url}

Valid Examples

http://{user_id}.pixelcrush.io/cdn/docs.pixelcrush.io/css/bootstrap.min.css
http://{user_id}.pixelcrush.io/cdn/https://3n14nr.pixelcrush.io/docs.pixelcrush.io/css/bootstrap.min.css

User Agent and robots.txt

As pixelcrush acts as a proxy, pixelcrush sends custom "User-Agent" header to be recognized by the server. At this time pixelcrush does not take care of robots.txt files and destination server should handle access limitation.

Mozilla/4.0 (compatible; pixelcrushbot 1.0/ http://www.pixelcrush.io)

Image Formats

You can convert between formats in real time using the f filter. The default format will be the same of the original proxied image.
Supported extensions are:"

  • jpg / jpeg (JPEG)
  • pjpg / pjpeg (Progressive JPEG)
  • png
  • gif
  • webp

JPEG

PJPEG

PNG

GIF

WEBP

Automatic WebP format delivery

Take advantage of the WebP format compression algorithm reducing file sizes with a minimal quality loss. You will automatically serve WebP images to browsers that support it, and then other formats such as PNGs or JPEGs to the other browsers.

Images are automatically delivered in WebP format under the following conditions:

  • You enable automatic WebP support in your control panel.
  • The browser which requests the image has WebP support.
  • The image has not explicit filter formats (eg. f=f(v=png) ).

Automatic WebP support can be enabled in the control panel under the section Settings.

NOTE: this functionality has an extra processing cost as the image is processed twice: one for browsers with WebP support and another one for those without it.

GET Parameters

f Chainable imaging filter.
nf Image of URL to be loaded if the original image is not found or there is any error in the operation. The status code will still be 404 or 40x.
ttl Time to Live in seconds. Creates the proper Content-Expiration Headers. Defaults to one month and with a maximun of 2 months.
auth HMAC authentication token.

Authentication

To prevent URL tampering and protect your bandwidth every call can be authenticated with an SHA-1 HMAC token.

Authentication can be enabled in the control panel under the section Account->Security.


<?php

$user_id        = ''; //your_id
$api_secret_key = ''; //your_api_secret_key
$target         = ''; //your_target_url
$url            = "http://{$user_id}.pixelcrush.io/{$target}";
$auth           = hash_hmac('sha1', 'GET' . $url, $api_secret_key);
$url            = $url . "&auth={$auth}";


#!/usr/bin/env python
# -*- coding: utf-8 -*-

import hashlib, hmac

user_id         = '' #your_id
api_secret_key  = '' #your_api_secret_key
target          = '' #your_target_url
url             = 'http://' + user_id + '.pixelcrush.io/' + target
auth            = hmac.new(api_secret_key, 'GET' + url, hashlib.sha1).hexdigest()
url             = url + '&auth=' + auth


/*
include file
src="http://crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/hmac-sha1.js"
*/

var user_id = ''; //your_id
var secret  = ''; //your_api_secret_key
var target  = ''; //your_target_url;
var url     = 'http://' + user_id + '.pixelcrush.io/' + target;
var auth    = CryptoJS.HmacSHA1('GET' + url, secret).toString()
    url     = url  + '&auth=' + auth;

Filter Aliases

To improve your image URLs and make them shorter pixelcrush.io can store "Filter Aliases" via the admin panel. Once the filter are setted the endpoints can be accessed as listed below.

URL Format
http://{user_id}.pixelcrush.io/{filter_name}/{image_url}

Origin Virtual Folders

Another way to improve your image URLs and make them shorter are "Origin Virtual Folders" which you can also create via the admin panel.
This is a convenient way to map a source url path to a shorter and more SEO-friendly name.

URL Format
http://{user_id}.pixelcrush.io/{virtual_folder}/{image_name}
Example:
Original URL:
http://3n14nr.pixelcrush.io/http://www.yourdomain.com/images/companylogo.jpg
Formatted URL:
http://3n14nr.pixelcrush.io/imgs/companylogo.jpg

Combining Filter Aliases and Origin Virtual Folders

A combination of Filter Aliases and Origin Virtual Folders can be used to achieve an even shorter version of your URLs.
You need to respect the following URL format as reversing the order of the parameters won't work.

URL Format
http://{user_id}.pixelcrush.io/{filter_alias}/{virtual_folder}/{image_name}
Example: (using previous configuration examples)
Original URL:
http://3n14nr.pixelcrush.io/http://www.yourdomain.com/images/product_main_image.jpg?f=rz(w=80,h=80)
Formatted URL:
http://3n14nr.pixelcrush.io/product_small/imgs/product_main_image.jpg


How to use CDN with Webfonts

When using Webfonts via @font-face or other CSS3 methods, most of mayor browsers like Chrome or Firefox will refuse to embed the font when it’s coming from a 3rd party URL because it’s a security risk.
This will be the case if you are using your default's custom domain "user_id.pixelcrush.io" as your resource proxy for font files.

The solution is very simple, just add a few lines in your webserver's configuration file to permanently solve the problem.

Apache webserver: .htaccess file

<IfModule mod_headers.c>
    <FilesMatch "\.(ttf|ttc|otf|eot|woff|woff2|font.css)$">
        Header set Access-Control-Allow-Origin "*"
    </FilesMatch>
</IfModule>   
NginX webserver: nginx.conf file

location ~ \.(ttf|ttc|otf|eot|woff|woff2|font.css)$ {
    add_header Access-Control-Allow-Origin "*";
}                    

Custom Domains

Using your custom domains to proxied images

Every Image CDN has many custom domains available; to improve your brand image, parallelize your images downloads, etc. They can be managed via the Pixelcrush Admin app or the Pixelcrush API.

Goal: Use your custom subdomain urls (http://mysubdomain.mydomain.com) instead pixelcrush’s default url format (http://{user_id}.pixelcrush.io).

Helpful links: How-to create a CNAME record on godaddy, namecheap, 123-reg, cPanel.

Add new domain

Step 1:

Adding an intermediate registration CNAME to validate your domain.

You need to use a cdnverify CNAME record subdomain to provide a registration step for the following custom domains you will create on your account.

To achieve this, you will need to add a CNAME record into your DNS zone on your domain registrar with format cdnverify.mysubdomain.mydomain.com pointing to your account’s cdnverify endpoint.

Your DNS mapping should look like:

cdnverify.mysubdomain.mydomain.com CNAME cdnverify.pix-{user_id}.azureedge.net

Step 2:

Add your custom domain into your Image CDN domains’ tab for verification.

After adding it, your custom domain will append to your Domain Zones list and verification process will begin in background.

Due to CDN pops propagation times, your custom domain verification may take up to 120 minutes. In the meantime, a gray icon will be shown on the status column.

Once propagation has took place and our servers have validated it, the status will show a gray icon pointing that your custom domain is not a CNAME of your account’s production CNAME.

Step 3:

Add your custom domain CNAME record into your DNS zone on your domain registrar pointing to your account’s production CNAME.

Your DNS mapping should look like:

mysubdomain.mydomain.com CNAME {user_id}.pixelcrush.io

Once this step is done and propagation of your new CNAME mysubdomain.mydomain.com has took place, the status will show a green icon pointing that this custom domain is ready to use on your production proxied URLs.

Domain SSL

Once your custom domain is ready you can request the SSL activation following these steps:

Step 1:

Request the SSL activation by clicking in the button , the status will show a gray icon pointing that this custom domain is ready to use but SSL activation request still in process

Step 2:

After you enable SSL on your custom domain, DigiCert validates ownership of your domain by contacting the registrant for your domain, according to the domain's WHOIS registrant information. Contact is made via the email address (by default) or the phone number listed in the WHOIS registration.

In addition, DigiCert will send the verification email to the following addresses. If the WHOIS registrant information is private, verify that you can approve directly from one of these addresses:

  • admin@<your-domain-name.com>
  • administrator@<your-domain-name.com>
  • webmaster@<your-domain-name.com>
  • hostmaster@<your-domain-name.com>
  • postmaster@<your-domain-name.com>

You should receive an email in a few minutes, similar to the following example, asking you to approve the request. If you are using a spam filter, add admin@digicert.com to its whitelist. If you don't receive an email within 24 hours, contact Pixelcrush support.

When you click on the approval link, you will be directed to the following online approval form:

After approval, DigiCert will add your custom domain name to the Subject Alternative Names (SAN) certificate. The certificate is valid for one year and will be auto-renewed before it's expired.

You must complete domain validation before SSL will be active on your custom domain. You have six business days to approve the domain. Requests that are not approved within six business days will be automatically canceled.

Step 3:

After the domain name is validated, it can take up to 6-8 hours for the custom domain SSL feature to be activated. When the process is complete, the status will show a green icon pointing that this custom domain is ready to use and SSL is enabled. Your custom domain is now ready to use SSL.

Disabling SSL

Request the SSL deactivation by clicking in the button , the status will show a gray icon pointing that this custom domain is ready to use but SSL deactivation request still in process

After the custom domain SSL feature is disabled, it can take up to 6-8 hours for it to take effect. When the process is complete, the status will show a green icon pointing that this custom domain is ready to use and SSL is disabled. Your custom domain can no longer use SSL.

Delete domain

Once a custom domain is created it can be deleted at any time by clicking in the button . When the process is complete, the custom domain will can no longer available

Filters

Chainable as JQuery

Our filters has been designed with developers in mind. They can be imperatively chained using jquery style to create the desired version of your image.

We think that this way is much powerful, easy and expressiveness than setting fixed parameters in the url like the RIAPI specification.

Filters are named arguments functions where not every parameter is mandatory since every filter has been setted with default parameters to make them as short as possible.

Filters are processed from left to right; this means that the image input of every filter is the processed output of the filter at its left.

Original

f=crp(w=180,h=180)
f=crp(w=180,h=180).gre()
f=crp(w=180,h=180).gre().wrk(a=.4,u=https://3n14nr.pixelcrush.io/docs.pixelcrush.io/img/logo_1000.png)

Filters Summary

Format

f(v=[gif|jpg|jpeg|pjg|pjpeg|png|webp|mp4])

mp4 format is only available for gif resources.

Parameter Required Default Description
v yes Format

Quality

q(v=[0,1])
Parameter Required Default Description
v no .75 Quality value. It sets the quality compression for compressed formats.

Original

JPG .75 by default

JPG q(v=.9)

JPG q(v=.1)

Resize

rz(w=width,h=height,o=[empty|f|s|ft|ct|cb|cl|cr|cc],m=[0|1],p=[tl|tc|tr|cr|cc|cl|bl|bc|br],b:fff)
Parameter Required Default Description
w no original width width in pixels.
h no original height height in pixels.
o no operation. Available operations are fill, stretch, fit, crop top, crop bottom, crop left, crop right, crop center or default.
m no 0 max resolution. If setted to 1 the image is never scaled up. This feature is available with default and fill operation.
p no cc position. This feature is available with fill operation.
b no fff background color. Hex value without #. This feature is available with fill operation. Is ignored if the image type has alpha channel.

Original (700x306)

rz(w=150) (150x66)

rz(h=150) (343x150)

rz(w=150,h=150) (150x66)

rz(w=200,h=150,o=f,b=000) (150x66)

rz(h=150,o=s) (700x150)

rz(w=150,h=150,o=s) (150x150)

rz(w=150,h=150,o=ft) (150x150)

rz(w=150,h=150,o=cl) (150x150)

Crop

crp(w=width,h=height,p=[tl|tc|tr|cr|cc|cl|bl|bc|br|smart],x=empty,y=empty)
Parameter Required Default Description
w no original width width in pixels.
h no original height height in pixels.
p no smart position; additionally by defult the center point is calculated by our smart crop; which calculates the center of mass of the most interesting part of the image. If x and y are setted this is ignored.
x yes if y empty x position. Sets the x axis of the start point of the rectangle to crop.
y yes if x empty y position. Sets the y axis of the start point of the rectangle to crop.

Original (700x306)

crp(w=200,h=200)

crp(w=200,h=200,p=cc)

crp(x=200,y=150,w=200,h=120)

Watermark

wrk(a=[0,1],s=empty|[0,],sp=[1,99],p=[tl|tc|tr|cr|cc|cl|bl|bc|br],u=url-of-image)

The parameter u is mandatory to be the last parameter specified.

Parameter Required Default Description
u yes url of the thumbnail image.
a no 1 alpha. Determines the opacity of the watermark.
sp no Size percent for the watermak image respect final image width, if sp and s are present, sp takes precedence.
s no scale. Scales the size of the watermark image n times.
p no br Watermark position.
b no 0 Offset border.

Original

wrk(sp=30,u=https://docs.pixelcrush.io/img/logo_1000.png)
wrk(a=.4,u=https://docs.pixelcrush.io/img/logo_1000.png)
wrk(s=.3,p=br,u=https://docs.pixelcrush.io/img/logo_1000.png)

text

text(t='some text',p=[tl|tc|tr|cr|cc|cl|bl|bc|br], f=[empty|Some-Font], s=[empty|[1,]], c=RRGGBBAA)
Parameter Required Default Description
t yes empty Text overlay inside single quotes.
p no br Text position.
f no Arial Font families available: [Andale-Mono, Arial, Arial-Black, Bitstream-Charter, Calibri, Cambria, Candara, Comic-Sans-MS, Consolas, Constantia, Corbel, Courier-10-Pitch, Courier-New, Dialog, DialogInput, Georgia, Impact, Monospaced, SansSerif, Serif, Tahoma, Times-New-Roman, Trebuchet-MS, Utopia, Verdana, Webdings].
s no 20 Font size.
c no ffffffff Text color in RGBA format, hex value without #.

Original

text(t='TEXT', c=00000099, s=40)

text(t='TEXT',c=00000099, s=40, p=cc)

text(t='TEXT', f=Comic-Sans-MS, s=40)

Moderation

mod()

You can moderate adult (NSFW) images with this filter. Making use of it will detect if the image is suitable for moderation.
If so, the image will be replaced by the default moderated url image configured in your account, otherwise we will use our default moderation image.

Moderated Image Setting
Pixelcrush Default Moderated Image Default Moderation Image

Flip

flp(v=[h|v])
Parameter Required Default Description
v no h Flip value. vertical if specified; horizontal in any other case.

Original

flp()

flp(v=v)

Rotate

rot(d=degrees)
Parameter Required Default Description
d no 0 degrees to rotate the image clockwise. If 0 extracts the rotation information from the EXIF metadata. If the image has no alpha channel the result image is filled with the default color #fff.

Original

PNG rot(d=45)

JPEG rot(d=45)

JPEG rot(d=45).bg(c=000)

Grayscale

gre()

Original

gre()

Invert

inv()

Original

inv()

Sepia

sep(v=[0,100])
Parameter Required Default Description
v no 40 Intensity value.

Original

sep()

sep(v=80)

sep(v=10)

Pixelate

pix(v=[1,],f=[all|face_pos])
Parameter Required Default Description
v no 5 Pixel size value.
f no Face index from left to right, top to bottom, all to includes every detected faces.

Original

pix()

pix(v=20)

Original

pix(f=all,v=7)

pix(f=2,v=7)

Quantize

qtz(c=[1,],d=[0|1])
Parameter Required Default Description
c no 256 Max number of colors.
d no 1 Enable dither.

Original

qtz()

qtz(d=0)

qtz(c=16)

Blur

blr(r=[0,],o=[b,g],f=[all|face_pos])
Parameter Required Default Description
r no 2 radius.
o no b operation. box blur or gauss. While box if faster gauss is smoother.
f no Face index from left to right, top to bottom, all to includes every detected faces.

Original

blr()

blr(o=g)

blr(r=5)

Original

blr(f=all,o=g,r=10)

blr(f=1,o=g,r=10)

Sharpen

shp(i=[1,])
Parameter Required Default Description
i no 1 iterations.

Original

shp()

shp(i=2)

shp(i=3)

Noise

noi(a[0,],d=[0,1],m=[0|1])
Parameter Required Default Description
a no 25 amount.
d no 0.1 density.
m no 0 monochrome. If 1 the generated noise is monochrome.

Original

noi()

noi(m=1)

noi(a=50,d=.5,m=1)

Remove Noise

rno(i=[1,])
Parameter Required Default Description
i no 1 iterations.

Original

rno()

Contrast

con(v=[0,1])
Parameter Required Default Description
v no 1 Intensity value.

Original

con(v=.5)

con(v=1)

Brightness

bri(v=[0,])
Parameter Required Default Description
v no 1 Intensity value.

Original

bri(v=.5)

bri(v=1)

Auto Enhance Contrast and Brightness

enh()

Original

enh()

HSB

hsb(h=[0,],s=[0,],b=[0,])
Parameter Required Default Description
h no 0 hue level.
s no 0 saturation level.
b no 0 brightness level.

Original

hsb(h=.5)

hsb(s=.5)

hsb(b=.5)

RGB

rgb(r=[0,],g=[0,],b=[0,])
Parameter Required Default Description
r no 0 red channel.
g no 0 green channel.
b no 0 blue channel.

Original

rgb(r=10)

rgb(g=10)

rgb(r=5,g=2,b=10)

faces

faces(i=[all,1,],p=[1,2])
Parameter Required Default Description
i no all Face index from left to right, top to bottom, all to includes every detected faces.
p no Padding to apply on the resultant image.

Original

faces(p=1.2)

faces(i=4,p=1.5)

gif

gif(fr=[1,2,], fps=[1,2,], r=[yes|no], l=[1,2,])
Parameter Required Default Description
fr no empty Select the frame number fr from the gif.
fps no empty Frames per second.
r no No Revert the frames order.
l no empty Times the gif animation will loop.

Original

gif(fr=30)

gif(fps=20)

gif(r=yes)

gif(l=3)

gif(fps=20,r=yes)

Filter Alias

f=alias

User defined alias name can be passed as an argument instead using it as a virtual folder on the URL.

https://3n14nr.pixelcrush.io/docs.pixelcrush.io/grey_pix/img/demo1.jpg
https://3n14nr.pixelcrush.io/docs.pixelcrush.io/img/demo1.jpg?f=grey_pix

Filter Positions

Name Description
tl top left
tc top center
tr top right
cr center right
cc center center
bl bottom left
bc bottom center
br bottom right