API Documentation

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

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 :

{ 
"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
    }]
}
                                    

{ 
"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"
    }]
}
                                    

Access-Control-Allow-Origin: *