Overview

Pixo’s Image Editing API allows you to manipulate images by sending them together with a changes payload to a REST endpoint. This API implements most of the features of Pixo Editor and guarantees you the same results as if they were edited with the front-end Editor.

API endpoint

https://pixoeditor.com/api/image

Methods

GET https://pixoeditor.com/api/image/<JSON payload>

POST https://pixoeditor.com/api/image/<JSON payload>

POST https://pixoeditor.com/api/image --body <JSON payload>

Response

HTTP Status 200 and body containing the modified binary image.

HTTP Status 4xx in case of invalid input + JSON object in the response body containing the error message.

HTTP Status 5xx in case of server error + JSON object in the response body containing the error message.

Payload

Request payload must be a JSON object providing source of the edited image + modifications that should be applied to it.

• apikey String Your API key. IMPORTANT! Make sure that you protect your API key from your Control Panel by white-listing the IP address(es) of your server(s)!
• src String base64-encoded source image or URL to the source image; required when the request content-type is application/json
• image Binary source image; required when the request content-type is multipart/form-data
• output Object Settings for output image’s quality and format. See the Output Object structure
• filter String See list of available filters
• text Array of Objects See the Text Object structure
• stickers Array of Objects See the Stickers Object structure
• crop Object See the Crop Object structure
• rotate Number Rotation of the image in º . Valid values are 90, 180, 270
• flip String Flip of the image horizontally or vertically. Valid values are "hor" and "ver"
• adjust Object See the Color Adjustments Object structure
• shape String See list of available shapes
• frame Number Frame index of the image frame to be applied
• background Object See Background Object structure

Examples

The easiest way to test the REST Editing API is to open the below link in your web browser, just replace yourapikey with your real API key:

https://pixoeditor.com/api/image/{“apikey”:”yourapikey”,”src”:”https://pixoeditor.com/editor/shared/images/logo.png”,”filter”:”Sepia”}

Or you can try the following cURL commands (just replace yourapikey with your real API key and input.jpeg with path to real image file on your computer:

curl -X POST -F 'apikey=yourapikey' -F 'filter=Sepia' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

curl -X POST -F 'apikey=yourapikey' -F 'text=[{"text":"Hello"},{"text":"world","position":"top-right"}]' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

curl -X POST -H "Content-Type: application/json" -d '{"apikey":"yourapikey","filter":"Sepia","src":"'$(base64 -i input.jpg)'"}' https://pixoeditor.com/api/image > output.jpg

Modifications

Output

curl -X POST -F 'apikey=yourapikey' -F 'filter=Sepia' -F 'output={"format":"png"}' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

• format (String) Image format (type), can be one of the following:
  • "auto" Default Detects output format by smart image analysis (transparency (alpha), number of colors, gradients, and more) and determines the best format (png or jpeg) in terms of alpha, higher quality and lower filesize
  • "input" Preserves the input format, but only in case it is jpeg or png. For any other format, the above behavior is applied
  • "jpeg" Forces jpeg format. Note: transparent pixels will appear black
  • "png" Forces png format. Note: output image may become very large (megabytes)
  • "webp" Forces webp format.
• quality (Number) Value between 0 and 1, closer value to 1 results in higher quality, and vice-versa. Applies only if the output format is jpeg or webp. Default 0.65
• optimize (Boolean) Image compression by TinyPNG. Optimizing images will result in less KB (optimzied filesize) as well as slower image export. Default false

Filter

curl -X POST -F 'apikey=yourapikey' -F 'filter=Sepia' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

List of available filters:

• Natural
• Amarok
• Klarendon
• Larc
• Mayfare
• Autumn
• Nightfall
• Sepia
• Grayscale
• BlackWhite
• Brownie
• Vintage
• Kodachrome
• Technicolor
• Polaroid
• Reddish
• Redify
• Convolute-Sharpen
• Convolute-ExtraSharp
• Convolute-Light
• Convolute-Dark
• Convolute-Blur
• Convolute-Emboss
• Invert
• Distressed

Text

curl -X POST -F 'apikey=yourapikey' -F 'text=[{"text":"hello, world!"}]' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

• text String the text message to insert
• position (optional) String or Object with the following possible values:
  • "top"
  • "top-left"
  • "top-right"
  • "left"
  • "center"
  • "right"
  • "bottom"
  • "bottom-left"
  • "bottom-right"
  • Object with the following shape:
    • left Number The desired left boundary of the sticker image in pixels
    • top Number The desired top boundary of the sticker image in pixels
• offset Object (optional) with the following shape:
  • x Number The desired horizontal offset in pixels (when larger than 1 ) or % of edited image’s width
  • y Number The desired vertical offset in pixels (when larger than 1 ) or % of edited image’s height
• width Number (optional) The desired width of the text box. If the value is greater than 1 the width is set in pixels; otherwise it would be considered as a % of the edited image’s width, e.g. 0.65 = 65% of the edited image’s width. If not provided the width of the text box will be as big as the text inside.
• height Number (optional) The desired height of the text box. If the value is greater than 1 the height is set in pixels; otherwise it would be considered as a % of the edited image’s height, e.g. 0.65 = 65% of the edited image’s height. If not provided the height of the text box will be as big as the text inside.
• fontFamily String (optional) one of the following:
  • Arial
  • Verdana
  • Times New Roman
  • Georgia
  • Comic Sans MS
  • Pacifico
  • Roboto Condensed
  • Oswald
  • PT Sans
  • Open Sans Condensed
  • Ubuntu
  • PT Sans Narrow
  • Lobster
  • Yanone Kaffeesatz
  • Play
  • Amatic SC
  • Comfortaa
  • Poiret One
  • Russo One
  • Philosopher
  • Caveat
  • Jura
  • Marck Script
  • Bad Script
  • Montserrat Alternates
  • Neucha
  • Press Start 2P
  • Pattaya
• fontSize Number (optional) from 10 to 100
• lineHeight Number (optional) from -50 to 50
• charSpacing (optional) Number
• fontWeight String (optional) one of the following:
  • normal
  • bold
• fontStyle String (optional) one of the following:
  • normal
  • italic
• underline (optional) Boolean
• linethrough (optional) Boolean
• superscript (optional) Boolean
• subscript (optional) Boolean
• fill String (optional) any valid CSS color (incl. rgba)
• textShadowColor (optional) String any valid CSS color (incl. rgba)
• textShadowOffsetX (optional) Number from -20 to 20
• textShadowOffsetY (optional) Number from -20 to 20
• textShadowBlur (optional) Number from 0 to 12
• strokeWidth (optional) Number  from 0 to 12
• textBackgroundColor (optional) String any valid CSS color (incl. rgba)
• backgroundColor String any valid CSS color (incl. rgba)

Stickers

curl -X POST -F 'apikey=yourapikey' -F 'stickers=[{"src":"https://yourdomain.com/path/to/image.png"}]' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

Array of Objects each having the following structure:

• src String The URL of the sticker image to be inserted
• width Number (optional) The desired width of the sticker image. If the value is greater than 1 the width is set in pixels; otherwise it would be considered as a % of the edited image’s width, e.g. 0.65 = 65% of the edited image’s width. If not provided the natural width of the sticker image would be used unless larger than the edited image’s width.
• height Number (optional) The desired height of the sticker image. If the value is greater than 1 the height is set in pixels; otherwise it would be considered as a % of the edited image’s height, e.g. 0.65 = 65% of the edited image’s height. If not provided the natural height of the sticker image would be used unless larger than the edited image’s height.
• position (optional) String or Object with the following possible values:
  • "top"
  • "top-left"
  • "top-right"
  • "left"
  • "center"
  • "right"
  • "bottom"
  • "bottom-left"
  • "bottom-right"
  • Object with the following shape:
    • left Number The desired left boundary of the sticker image in pixels
    • top Number The desired top boundary of the sticker image in pixels
• offset Object (optional) with the following shape:
  • x Number The desired horizontal offset in pixels (when larger than 1 ) or % of edited image’s width
  • y Number The desired vertical offset in pixels (when larger than 1 ) or % of edited image’s height

Crop

curl -X POST -F 'apikey=yourapikey' -F 'crop={"ratio":1.5}' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

curl -X POST -F 'apikey=yourapikey' -F 'crop={"left":10,"top":10,"width":200,"height":200}' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

curl -X POST -F 'apikey=yourapikey' -F 'crop={"type":"face"}' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

The crop object has the following shape:

• ratio Number Crops the image with specific crop aspect ratio

or

• left Number Left boundary in pixels
• top Number Top boundary in pixels
• width Number Width in pixels
• top Number Height in pixels

or

• type String having one of the following values:
  
  • "face" : performs a face detection and crops the face if detected
• buffer Number buffer added to the crop

Color Adjustments

curl -X POST -F 'apikey=yourapikey' -F 'adjust={"brightness":0.2}' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

• brightness: -1 to 1
• contrast: -1 to 1
• hue-rotation: -2 to 2
• saturation: -1 to 1
• gamma-red: 0.01 to 2.2
• gamma-green: 0.01 to 2.2
• gamma-blue: 0.01 to 2.2
• blur: 0 to 1
• noise: 0 to 1000
• pixelate: 2 to 20

Shapes

curl -X POST -F 'apikey=yourapikey' -F 'shape=circle' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

List of available shapes:

• rhombus
• circle
• ellipse
• diamond
• star
• hexagon
• octagon

Background

curl -X POST -F 'apikey=yourapikey' -F 'background={"type":"transparent"}' -F '[email protected]' https://pixoeditor.com/api/image > output.jpeg

The background object has the following shape:

• type String The type of the background with one of the following values:
  • "transparent"
  • "solidcolor"
  • "replacement"
• bgcolor String CSS Color (rgba supported) for the new background. Applicable only if the type is "solidcolor"
• src String URL (could be also dataurl or base64) of the replacement background image. Applicable only if the type is "replacement"