API Documentation

How to integrate your own photos and images into your embedded studio




For new subscribers joining Pixelixe after March 21th 2021, access the more recent V2 documentation here. For older subscribers, don't worry, this V1 documentation will remain supported and active indefinitely. Get more detail regarding the new V2 release and upgrade prerequisites here.

Introduction :

With your "white-label" Studio, you can integrate your own assets (photos, background images and so on) to let your users and visitors create engaging graphics using your own content

As a variety of our customers owns a huge amount of images and photos (sometimes hundreds of thousands), we decided to not allow the uploading of those assets directly into our Pixelixe's servers.

Two main reasons for this decision :
  • First, the synchronisation between our customers asset collection and our servers will have been a real nightmare.
  • Second, the storage of those duplicated photos does not match our enviromental values.


Consuming data directly from our customers platform using APIs prevent data duplication and therefore will contribute in reducing carbon footprint and also guarantee that data (images and photos) integrated in the studio are up to date with your servers.
To add new images to the studio, you just have to enrich the API exposition on your side and that's it.

How to expose your digital assets through an API compliant with Pixelixe default requirements



As you understood from the introduction above, the best way to integrate your own content into the editor is by exposing your images and photos with a searchable API. Once integrated, this API will be the entry point to search your images collection using keywords chosen by your users.

From the "Customization tool", you will be able to choose which section you want to customize and you will be asked to input each of your API URLS.

Two options, for example, to integrate your own images inside the Studio, you can choose to replace the existing background collection from the center left "Background" menu (section "Images) or you can choose to replace standard images from the center left "Graphics" menu (Section Images). Either, you can choose to set up the same API exposing your images or to create two distincts APIs (exposing different content).



Pixelixe default API requirements



HTTP Header: Basic HTTP authentication (Optional)



https://en.wikipedia.org/wiki/Basic_access_authentication

With your Pixelixe API key (REMINDER: find it from your dashboard) you can start building then publishing your own search images API. To secure access to your assets, you can set up Basic HTTP authentication. With this feature, a HTTP Authorization header will secure access to each  HTTP requests you will receive from your users through your white-label Studio. This will prevent anyone to access or consume your precious data. 

By default, Pixelixe Studio will automatically add this HTTP header in each call of your APIs. Basic authentication is optional, that means you are free to not implement it on your side of the API. Keep in mind that you take full responsibility to not set up authentication.


This HTTP header will be set up each time the studio will consume your API:

Authorization: Basic YOUR_API_Key


HTTP Header: Cross-Origin Resource Sharing



Then, to authorize the remote Pixelixe editor to access this API exposed from your server, you must allow Cross-Origin Resource Sharing (CORS).

What is CORS ? CORS is a standard HTTP header to secure access of resources on the internet.

Add Access-Control-Allow-Origin: https://studio.pixelixe.com or a less secure alternative Access-Control-Allow-Origin: * to your HTTP response header to grant Pixelixe permission to access it.
https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

Add the following HTTP Header in the HTTP Response of all your images :

Access-Control-Allow-Origin: *


Every web platform, even CMS such as Wordpress or similar can setup CORS settings.


HTTP Request parameters



When consuming your API, the Studio will send inside each request the 3 parameters below :
Parameter Type # Description
query string Required Get photos related to this query/keyword. If empty, must return a list of random photos. This parameter will be filled in by your users via the Studio search form field.
per_page integer Optional Defines the number of results per page/call.
page integer Optional Defines the number of the page. (Default 1)

The "per_page" and "page" parameters will be used to paginate your content. If you want to expose a huge amount of photos or background images, it becomes mandatory to paginate your API. Otherwise, if you just want to integrate a couple of dozens of images, you can skip those parameters.


HTTP Response Body



If the HTTP request is successful, the response body must be a JSON with the following data:

{ 
"page": 1, 
"per_page": 15, 
"total_results": 236, 
"photos": [{ 
    "width": 1000, 
    "height": 1000, 
    "raw": "https://YOUR_SITE/YOUR_FOLDER/1.jpg", 
    "thumbnail": "https://YOUR_SITE/YOUR_FOLDER/1.jpg"
    }, {
     // NEXT PHOTOS
    }]
}
                                    


Example :
{ 
"page": 1, 
"per_page": 3, 
"total_results": 3, 
"photos": [{ 
    "width": 1000, 
    "height": 1000, 
    "raw": "https://YOUR_SITE/YOUR_FOLDER/1.jpg", 
    "thumbnail": "https://YOUR_SITE/YOUR_FOLDER/1_small.jpg"
    }{ 
    "width": 1000, 
    "height": 1000, 
    "raw": "https://YOUR_SITE/YOUR_FOLDER/2.jpg", 
    "thumbnail": "https://YOUR_SITE/YOUR_FOLDER/2_small.jpg"
    },{ 
    "width": 1000, 
    "height": 1000, 
    "raw": "https://YOUR_SITE/YOUR_FOLDER/3.jpg", 
    "thumbnail": "https://YOUR_SITE/YOUR_FOLDER/3_small.jpg"
    }]
}
                                    

JPEG or PNG photos are supported.

Last step

Finally, to authorize the remote Pixelixe editor to access all your images served by your server, you must allow Cross-Origin Resource Sharing (CORS).

What is CORS ? CORS is a standard HTTP header to secure access of resources on the internet.

Add Access-Control-Allow-Origin: https://studio.pixelixe.com or a less secure alternative Access-Control-Allow-Origin: * to your HTTP response header to grant Pixelixe permission to access it.
https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

Add the following HTTP Header in the HTTP Response of all your images :

Access-Control-Allow-Origin: *


Every web platform, even CMS such as Wordpress or similar can setup CORS settings.