API Documentation

How to embed your customized studio inside your webapp (IFRAME integration)




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 :
Pixelixe provides one unique URL based API to let you embed our graphic/image creation tool in your webapp or website within an IFRAME.

WARNING : The minimum iframe width to display the studio is 1000 px (pixels).

The API parameters


GET https://studio.pixelixe.com/#api

Parameter Type # Description
apiKey string Required The API Key is the only way to authenticate your application with Pixelixe. A unique API key is provided after you signup to our API plan.

Ex : 6nm3JE0GoVWUai2wNEWiTLF66rk1
width integer Optional Use the width and height parameters (pixel) to open the Studio with a new blank document sized with those dimensions.

Ex : 
https://studio.pixelixe.com/#api?apiKey=6nm3JE0GoVWUai2wNEWiTLF66rk1&width=1000&height=300
height integer Optional Use the width and height parameters (pixel) to open the Studio with a new blank document sized with those dimensions.

Ex : 
https://studio.pixelixe.com/#api?apiKey=6nm3JE0GoVWUai2wNEWiTLF66rk1&width=1000&height=300
pdf string Optional Set the optional "pdf" parameter to true pdf=true in order to receive graphics created
by your users/visitors as PDF document. As soon as your visitors and users will finish
editing from your embedded studio. A PDF will be pushed to your server (HTTP Post to your OUTPUT URL).
pdfMargin string Optional Set the "pdfMargin" parameter to choose the margin of generated PDF (choose a pixel based margin, 0 by default).
debug boolean Optional Set debug=true to be alerted with popups (alert) when API parameter errors occured.
Useful to setup Pixelixe's API for the first time. (DO NOT USE THIS PARAMETER IN PRODUCTION). This parameter is set to false by default.
uid string Optional uid is an optional parameter. The "UID" parameter (Unique identifier) is available to
retrieve contextual data from the browser(front-end) on your server (back-end) when posting graphics.

For example, you can use the "UID" parameter to pass alongside each studio opening request
(browser side) your internal "Customer" or "User" identifier data that will allow you
to easily match "who created what" once our API will push (POST) output designs to your server endpoint on your OUTPUT URL.
You have full control over this UID so you can set whatever fits your need (even more than just your Customer Number if you want).
(Configure your "OUTPUT" URL).

This way you have an easy way to match connected users on your site with their documents posted on your server.
imageUrl string Optional The imageUrl allow to open any remote image inside the studio with a basic URL.

Use encodeURI when passing the imageUrl as an API parameter.
Ex : https://yourwebsite/yourimage.png
will become
https%3A%2F%2Fyourwebsite%2Fyourimage.png
graphicUrl string Optional Use graphicUrl to open the studio with a previously exported HTML Pixelixe document
(graphic/image). Previously exported meaning previously pushed to your OUTPUT URL and stored on
your site. This parameter is useful if you want to let your users re-edit and update their
graphics/images within the studio anytime. It is mandatory to send both "graphicUrl"
and "graphicName" parameters to reopen the document properly. The graphicUrl parameter
must be an HTTP URL linking directly to a HTML file.

WARNING : As a reminder, the Studio can edit HTML templates only if they have been exported/downloaded from the Studio itself. (You cannot import external HTML files.)


Find here how to get and store the graphic/image edited by your users. .

Two prerequisites:
1°) Use encodeURI when passing the graphicUrl as an API parameter.
Ex : https://yourwebsite/2Fyoururl.html
will become
https%3A%2F%2Fyourwebsite%2Fyoururl.html

2°) WARNING: your HTTP URL must allow Cross-Origin Resource Sharing (CORS).
Add the following element in your HTTP request header to make it downloadable in the studio :
Access-Control-Allow-Origin: https://studio.pixelixe.com
graphicName string Optional Use graphicName To re-edit and update a graphic/image within the studio. It is required to send
both "graphicUrl" and "graphicName" parameters. We strongly recommend to use the "encodeURI"
Javascript function to encode the graphicName to make sure to correctly handle special
characters within the URI.
outputURL string Optional Use "outputURL" to change the "endpoint" (redirect URL) and overwrite the "OUTPUT" URL set up
from the Customization tool. If not set, by default, the studio will use the one you set up in the "Customization tool".

Use encodeURI when passing the outputURL as an API parameter.
Ex : https://yourwebsite/yourendpoint
will become
https%3A%2F%2Fyourwebsite%2Fyourendpoint
lang string Optional Translate the editor in the language of your choice() Ex: &lang=fr ). French, Portuguese and English are already available by default. Contact us at inquiries@pixelixe.com if you need another language support and we will help you setup your account.
templates boolean Optional Pass the "templates" parameter set to "true" to display Pixelixe's default premade
formats & templates when your embedded Studio will open. (check out Our free studio to discover our templates (See example below).

Example : API call to create a blank graphic/image

Use the width (pixel) and height (pixel) parameters to choose the dimension of the new blank document. 
https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&uid=yourinternalid


Same example with IFRAME :

<iframe
    width="1200"
    height="1080"
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&uid=yourinternalid" >
</iframe>

Example : API call to edit an existing graphic (HTML exported document) stored on your server

Use the graphicUrl and graphicName parameters to open and re-edit an already exported document (graphic/image). 
https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&graphicUrl=https://yourwebsite.com/URL_TO_HTML_DOCUMENT.html&graphicName=NAME+OF+YOUR+DOCUMENT&uid=yourinternalid


Same example with IFRAME :

<iframe
    width="1200"
    height="1080"
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&graphicUrl=https://yourwebsite.com/URL_TO_HTML_DOCUMENT.html&graphicName=NAME+OF+YOUR+DOCUMENT&uid=yourinternalid" >
</iframe>

Example : API call to edit any remote image from a URL (Image Editor)

https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&imageUrl=https://any-website.com/any-image.png


Same example with IFRAME :

<iframe
    width="1200"
    height="1080"
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&templates=true" >
</iframe>

Example : API call to display Pixelixe's default templates list

https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&templates=true


Same example with IFRAME :

<iframe
    width="1200"
    height="1080"
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&templates=true" >
</iframe>

Example : API call to use the studio as a PDF editor

https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&pdf=true&pdfMargin=20


Same example with IFRAME :

<iframe
    width="1200"
    height="1080"
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&pdf=true&pdfMargin=20" >
</iframe>

Example : API call to programatically change your server endpoint (OUTPUT URL)

Convenient to integrate the editor into your DEV or STAGING environment. 
https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&outputURL=https://staging.yourwebsite/yourendpoint


Same example with IFRAME :

<iframe
    width="1200"
    height="1080"
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&outputURL=https://staging.yourwebsite/yourendpoint" >
</iframe>

Example : API call to translate the editor in the language of your choice

French (fr), Portuguese (po), English (en), Dutch (nl), Turkish (tr) are already available. Contact us to get your language setup for your account. 
https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&lang=fr


Same example with IFRAME :

<iframe
    width="1200"
    height="1080"
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300&lang=fr" >
</iframe>

TIPS : Example with FullScreen IFRAME


Fullscreen IFRAME : (Your users won't even notice they are using an external tool)

<iframe
     style="position:fixed; top:0; left:0; bottom:0; right:0; width:100%; height:100%; border:none; margin:0; padding:0; overflow:hidden; z-index:999999;"  
    allowfullscreen
    frameborder="0"
    src="https://studio.pixelixe.com/#api?apiKey=YOUR_API_KEY&width=1000&height=300" >
</iframe>