loading

REST Editing API

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/<payload>

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

POST https://pixoeditor.com/api/image --body <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.

Examples

curl `
    echo 'https://pixoeditor.com/api/image/{"apikey":"yourapikey","filter":"Sepia","src":"https://yourdomain.com/path/to/image.png"}' \
    | sed s/\"/%22/g | sed s/{/%7B/g | sed s/}/%7D/g # urlencode the JSON payload
` --output image.png
curl `
    echo 'https://pixoeditor.com/api/image/{"apikey":"yourapikey","frame":1}' \
    | sed s/\"/%22/g | sed s/{/%7B/g | sed s/}/%7D/g # urlencode the JSON payload
` -F "[email protected]" --output edited-image.png

Modifications

Output

  • 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

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

The “text” modification is an Array of Objects, each having the following shape and possible values:
  • 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:
    • 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 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 from 10 to 100
  • lineHeight Number from -50 to 50
  • charSpacing Number
  • fontWeight String one of the following:
    • normal
    • bold
  • fontStyle String one of the following:
    • normal
    • italic
  • underline Boolean
  • linethrough Boolean
  • superscript Boolean
  • subscript Boolean
  • fill String any valid CSS color (incl. rgba)
  • textShadow Boolean
  • textShadowColor String any valid CSS color (incl. rgba)
  • textShadowOffsetX Number from -20 to 20
  • textShadowOffsetY Number from -20 to 20
  • textShadowBlur Number from 0 to 12
  • textStroke Boolean
  • strokeWidth Number  from 0 to 12
  • textBackground Boolean
  • textBackgroundColor String any valid CSS color (incl. rgba)
  • background Boolean
  • backgroundColor String any valid CSS color (incl. rgba)

Stickers

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:
    • 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

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

Color Adjustments

List of property names and their value ranges:
  • 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

List of available shapes:

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

Background

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"