NAV
← Return to API Doc
API Documentation

API - Image Generation properties

6 components are currently available:

Additionally, the background of every format can be customized via the root element.

At the bottom, there is also a Q&A section to cover more specific aspects (such as 8-digits hexa color).

Image Background

Monochrome:
"background_color": "#610000"

Monochrome background color

As mentioned before, the root element can be used to customized the background of your image.

background_color: 2 filling modes are available:

Linear gradient

Linear gradient (horizontal):
"background_color": "linear-gradient(0% 0% 100% 0%,0% #1a47ff 1,100% #b65151 1)"

Horizontal Gradient background color

Linear gradient (vertical):
"background_color": "linear-gradient(0% 0% 0% 100%,0% #1a47ff 1,100% #b65151 1)"

Vertical Gradient background color

Linear gradient (diagonal):
"background_color": "linear-gradient(0% 0% 100% 100%,0% #1a47ff 1,100% #b65151 1)"

Diagonal Gradient background color

A linear gradient property can be used as background_color (banner background, button) & color (text).

String: linear-gradient(x1% y1% x2% y2%,offset_color1% hexa_color1 opacity_color1,offset_color2% hexa_color2 opacity_color2)

Gradient properties Description
x1, y1, x2, y2 Number (Percentage), can be negative. Define the straight line that will be used to draw the background.
offset_color1, offset_color2 Number (Percentage), can be negative. Define the offset of the starting & ending points (default: 0%, 100%)
hexa_color1, hexa_color2 String: 6 digits hexa color. Starting & ending colors
opacity_color1, opacity_color2 Float (between 0 & 1). Opacity of starting & ending colors

All components

Some properties are available for all components:

Property Description
hidden Boolean: true, false. Hide the current element
shadow_color
shadow_blur
shadow_offset_x
shadow_offset_y
Go to Shadow documentation

Shadow

shadow_color: "#00000080"
shadow_blur: 3
shadow_offset_x: 4
shadow_offset_y: 3
Text with shadow

Shadow can be added to all components.

Component specificities:

Text

Example of a decorated text:

"payload": "Lorem i<c=#ff0000><u>p</u></c>su<s>m</s> is simply <c=#1A47FF>dummy</c> <u>text</u>"
"color": "#ffffff"
"background_color": "#8A4F4F"
"background_padding": "2 6",
"skew_y": -4
"alignment": "middle center"
"font_size": 30
"line_height": 150
"shadow_color": "#00000080"
"shadow_blur": 3
"shadow_offset_x": 0
"shadow_offset_y": 6

Fully decorated Text

Available properties:

Property Description
payload Go to Payload documentation
color Go to Color documentation
background_color Same as color, but allows to add a background behind the text
background_padding Go to Background Padding documentation
font_size Number. Force font size in pixels (must be > 1)
font
font_weight
Go to Font documentation
line_height Number. Force line height in percentage (must be > 1). This parameter is only applied when the text is a multiline one.
skew_y Number: between -20 and 20. Slant text on the y axis
alignment Go to Alignment documentation
stroke_width
stroke_color
Go to Stroke documentation
shadow_color
shadow_blur
shadow_offset_x
shadow_offset_y
Go to Shadow documentation

Color

#1A47FF
Colored Text

linear-gradient(0% 0% 100% 0%,0% #0a68ff 1,100% #ff0000 1)
Gradient Colored Text

color: The text color, can be a monochrome (6-8 digits hexa color) or a gradient (Go to Linear Gradient documentation).

Constraint:

The 6 digits format is #RRGGBB and 8 digits is #RRGGBBAA. (R=red, G=green, B=blue, A=alpha). You can go to the Q&A section to understand 8 digits hex code.

Payload

Lorem Ipsum is simply dummy text
Normal text

payload is the text content.

Constraints:
How can I force specific line breaks?

Lorem Ipsum\nis simply dummy text
Text with forced line break

By default, line breaks are automatically computed from the available space. You can however force line breaks by adding \n.

Beware of external integrations (Zapier, Integromat, Airtable): as they support multi text line inputs this parameter won't be used.

How can I add decorations to specific parts of a text?

<c=#FF0000>Lorem Ipsum</c> is simply dummy text
Text with colored part

<w=900>Lorem Ipsum</w> is simply dummy text
Text with font-weight part

<u>Lorem Ipsum</u> is simply dummy text
Text with underline part

<u=#FF0000>Lorem Ipsum</u> is simply dummy text
Text with underline colored part

<s>Lorem Ipsum</s> is simply dummy text
Text with strike part

<s=#FF0000>Lorem Ipsum</s> is simply dummy text
Text with strike colored part

<bg=#f6aeb8>Lorem Ipsum</bg> is simply dummy text
Text with a background colored part

<c=#243659><w=900><u=#1A47FF>Lorem Ipsum</u></w></c> is simply <s>dummy</s> text
Text with combined decorations part

Text markups can be added to underline, colorize, strike of change font weight on specific part of the payload. (it resembles html markup but is not)

Text markups will override global decorations

Available markups (examples on the right):
Type Markup
Color <c={hexaColor}>my colored part</c>
Font weight <w={weight}>my colored part</w>

{weight}: Integer representing the font weight (100 to 900):
thin (100), normal (400), bold (700), heavy (900)).

If the font does not support the given weight, it fallbacks to the current weight.
Underline <u>my underline part</u>
Underline with colored line <u={hexaColor}>my colored underline part</u>
Strike through <s>my strikethrough part</s>
Strike through with colored strike <s={hexaColor}>my colored strike part</s>
Background color <bg={hexaColor}>Text with bg color</bg>

The padding around the background is controlled on the whole element (by using the background_padding property)

{hexaColor}: 6 or 8 (for the opacity) digits hexadecimal color starting with # (i.e. #EAEAEA or #00000080)

Of course all of those markups can be combined (look at the last example on the right). It works like HTML, hence beware of how you write your opening & closing tags.

Background padding

0 10
Text with small background padding

5 10
Text with big background padding

background_padding: The padding of the background color around the text.

This parameter will only be used if a background color is defined.

Stroke

stroke_width: 8
stroke_color: "#1A47FF"
Text with stroke colored

A stroke can be added to text. In order to customize it, 2 properties are available:

If your template does not contain any stroke, those 2 properties are required to have a stroke (and the width must be > 0).

Text Alignment

alignment: center
Text centered

alignment: right
Text right aligned

alignment can be defined to override the default text alignment. Text position will then be computed from the text bounding box defined within the template.

It can be of two forms:

Font

Podkova font:
font: "6156872a-33c5-11ea-9877-92672c1b8195"
font_weight: 500

Podkova regular font

Poppins font:
font: "6156907e-33c5-11ea-9877-92672c1b8195"
font_weight: 800

Poppins bold font

The default font can be overridden with the font and font_weight properties:

If the font does not contain a font weight, the nearest weight will be used.

Button

Example of a simple button:
"payload": "My click to action",
"color": "#FFFFFF",
"background_color": "#1A47FF"

Simple button

The button is basically a text with a background color behind.

Available properties:

Property Description
payload Same as Text Payload documentation
color Same as Text Color documentation
background_color Same as color
font
font_weight
Go to Font documentation
font_size Number. Force font size in pixels (must be > 1)
line_height Number. Force line height in percentage (must be > 1). This parameter is only applied when the text is a multiline one.
shadow_color
shadow_blur
shadow_offset_x
shadow_offset_y
Go to Shadow documentation

Image

Example of a decorated image:
"image_url": "https://local-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/ec7420ac-7f58-4b0c-834b-6abfffb9e5fb/assets/031bd708-f7df-4e5f-9da3-88d21fa7e520.jpeg",
"opacity": 90,
"fitting_type": "fill",
"alignment": "middle center",
"mask_name": "rounded_corners",
"mask_properties": {
   "radius": "20"
},
"filter_name": "duotone",
"filter_properties": {
   "name": "deep_blue_green"
},
"overlay_direction": "vertical",
"overlay_color_1": "#FF000080",
"overlay_color_2": "#0000FF1A"

Decorated fully image

Available properties:

Property Description
image_url String: HTTP(s) URL of your image. i.e: https://www.abyssale.com/imge/abyssale_logo.png

It must be a public accessible link and be 5 mo maximum.
Supported files: jpeg, png, webp, svg.
opacity Integer between 0 and 100. Opacity of the image
fitting_type Go to Fitting Type documentation
alignment Go to Alignment documentation
mask_name
mask_properties
Go to Mask documentation
filter_name
filter_properties
Go to Filter documentation
overlay_direction
overlay_color_1
overlay_color_2
Go to Overlay documentation
shadow_color
shadow_blur
shadow_offset_x
shadow_offset_y
Go to Shadow documentation
x
y
Go to Position documentation
width
height
Go to Dimension documentation

Fitting Type

fill
Filled image

cover
Covered image

fitting_type: That defines the way the image will be inserted in the bounding box.

Two properties are supported:

Alignment

(fitting_type: cover): alignment: middle center
Covered image centered

(fitting_type: cover): alignment: middle right
Covered image right aligned

(fitting_type: fill) alignment: bottom center
Filled image bottom aligned

(fitting_type: fill) alignment: middle center
Filled image centered

alignment can be defined to override the default image alignment.

It can be of two forms:

Mask

(fitting_type: fill) mask_name: circle
Image with a circle mask

(fitting_type: fill)
"mask_name": "rounded_corners",
"mask_properties": {
   "radius": 10
}
Image with a circle mask

A mask can be added to the image by using the mask_name property:

mask_properties: Dict. Only support radius (integer) as parameter. This parameter should only be used in combination with rounded_corners.

Filter

(Original image)
Original Image

filter_name: grayscale
Grayscaled Image

"filter_name": "duotone",
"filter_properties": {
   "name": "blue_orange"
}
Image with a duotone blue orange

A filter can be added to the image by using the filter_name property:

filter_properties: Dict. Only support name (string) as parameter. This parameter should only be used in combination with duotone.

Available list of duotone names:

Name Render
blue_orange Image with a duotone blue_orange
deep_green_light_green Image with a duotone deep_green_light_green
BrightRed_light_yellow Image with a duotone BrightRed_light_yellow
brown_pale_green Image with a duotone brown_pale_green
brown_beige Image with a duotone brown_beige
deep_blue_green Image with a duotone deep_blue_green
deep_blue_red Image with a duotone deep_blue_red
deep_purple_orange Image with a duotone deep_purple_orange
deep_purple_beige Image with a duotone deep_purple_beige
deep_purple_pale_green Image with a duotone deep_purple_pale_green
deep_blue_pale_green Image with a duotone deep_blue_pale_green

Overlay

Gradient:
"overlay_direction": "horizontal"
"overlay_color_1": "#FF000080" (alpha hexa 80 = 0.5)
"overlay_color_2": "#0000FF1A" (alpha hexa 1A = 0.1)
Image with gradient horizontal overlay

"overlay_direction": "vertical"
"overlay_color_1": "#FF000080"
"overlay_color_2": "#0000FF1A"
Image with gradient vertical overlay

"overlay_direction": "diagonal"
"overlay_color_1": "#FF000080"
"overlay_color_2": "#0000FF1A"
Image with gradient diagonal overlay

Monochrome
"overlay_direction": "horizontal"
"overlay_color_1": "#FF000080"
"overlay_color_2": "#FF000080"
Image with monochrome overlay

An (monochrome or gradient) overlay can be added to the image.

The 3 following properties are required:

If you want a monochrome overlay, just set the 2 colors properties with the same color (in that case, the direction is then useless).

Position

We will use image as an example but it works the same way for other components. You can move the image by using x (move horizontally) or y (move vertically)

Values can be written:

Values can be of two types:

Dimension

We will use image as an example but it works the same way for other components. You can resize the image by using width (resize horizontally) or height (resize vertically)

Values can be written:

Values can be of two types:

Example of a logo:
"image_url": "https://local-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/db3601c4-343a-4744-86cd-516d450b731b/assets/af3cb08b-9b56-41f1-a44e-bc837acacca7.svg",
"alignment": "top left"

Logo

Logo is a simplified version of the image component. There is no fitting, mask, filter & overlay properties.

Available properties:

Property Description
image_url String: HTTP(s) URL of your image. i.e: https://www.abyssale.com/imge/abyssale_logo.png

It must be a public accessible link and be 5 mo maximum.
Supported files: jpeg, png, webp, svg.
alignment Go to Alignment documentation
shadow_color
shadow_blur
shadow_offset_x
shadow_offset_y
Go to Shadow documentation
x
y
Go to Position documentation
width
height
Go to Dimension documentation

Shape

For now, the type (rectangle (with/without rounded corners), circle & triangle) of the shape can only be selected on the template side.

Example of a rectangle:
"background_color": "#1A47FF",
"pattern_name": "ticTacFilled",
"pattern_color": "#FFFFFF1A"

Simple shape with pattern

Available properties:

Property Description
background_color String: 6-8 digits Hexa color.
pattern_name
pattern_color
Go to Pattern documentation
stroke_width
stroke_color
Go to Stroke documentation
shadow_color
shadow_blur
shadow_offset_x
shadow_offset_y
Go to Shadow documentation
x
y
Go to Position documentation
width
height
Go to Dimension documentation

Pattern

A pattern can be added to the image by using the both the pattern_name & pattern_color properties.

List of pattern names:

Pattern name Render Pattern name Render
cross doubleCircle
parkay drops
star pills
triangle plus
wiggle ticTac
bubbles ticTacFilled
cage

Rating

Example of a rating:
"rating_score": 64,
"star_dimension": 40,
"star_margin": 10,
"star_color": "#FF0000",
"background_color": "#EAEAEA80"

Simple 5-stars rating

For now, 5 stars is the only available rating decoration.

Available properties:

Property Description
rating_score Number between 0-100. Score of the rating on a scale of 100.
star_dimension Number between 4-400. Size in pixels of one star.
star_margin
Number between 0-100. Martgins in pixels between stars.
star_color
String. 6-8 digits hexadecimal color. Represents the color of the filled stars.
background_color
6-8 digits hexadecimal color. Represents the background color of all stars.
shadow_color
shadow_blur
shadow_offset_x
shadow_offset_y
Go to Shadow documentation
x
y
Go to Position documentation
width
height
Go to Dimension documentation

Illustration

Example of a simple illustration:
"illustration_file": "good_team"
Simple illustration

You can find all illustrations here:

Available properties:

Property Description
illustration_file The illustration name.
illustration_properties Go to Illustration properties documentation
alignment Go to Alignment documentation
opacity Integer between 0 and 100. Opacity of the image
x
y
Go to Position documentation
width
height
Go to Dimension documentation

illustration properties

Undraw, feather and material icons can have illustration_properties.
primary_color is used to change the color of the illustration.

Property Description
primary_color String: 6-8 digits hexa color

Questions & Answers

What is a 8-digits hexadecimal color?

A classic hexa color is of the #RRGGBB form (6 digits hexa color with a starting #).
RR is red, GG is green & BB is blue.

The 8-digits form allows to add an alpha part (opacity) at the end of this 6-digits color. It is represented by the following form: #RRGGBBAA where AA if the hexadecimal of the opacity.
For instance: #FFFFFF80 represents the white color with a 50% opacity (80).

Here is the representation list of opacity (in percentage) to hexadecimal: (you can also find all values in this codepen)

Opacity (on a scale to 0-100) AA (Alpha Hexadecimal)
0 FF
5 0D
10 1A
20 33
30 4D
40 66
50 80
60 99
70 B3
80 CC
90 E6
100 00