Optidash API Reference - Operations

Image Operations / Typesetting

Typesetting enables the addition of both single- and multi-line text to your images. Optidash offers a comprehensive suite of controls for text positioning, font selection, color, padding, border, shadow, and alpha transparency, ensuring extensive customization options.

All parameters governing the typesetting behavior must be specified within a new top-level text key. To prevent any potential encoding issues, the text content itself must be base64-encoded. This encoded string should then be provided as the text value.

For instance, to render the phrase "Hello World" using the default settings:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK"
    }
}

Font Weight

The weight parameter defines the thickness of typeface's strokes. Available values are ultralight, light, normal, bold, ultrabold, heavy. The default setting is normal

For example, to set the font weight to bold:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold"
    }
}

Font Family

The font parameter specifies the font family to use for the text. The default font family is Arial. A full list of supported fonts can be downloaded from here.

For example, to set the font family to DejaVu Serif:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "font": "DejaVu Serif"
    }
}

Please feel free to reach out to us if you're interested in having a custom font installed on our rendering servers. We're here to accommodate your specific needs.

Font Style

The style parameter determines whether the font is rendered in a normal or italic style. The default font style is normal.

For example, to set the font style to italic:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "style": "italic"
    }
}

Text Color

The color parameter controls the text's color and accepts hex-encoded strings in RGB and RRGGBB formats.

For example, to set the font color to orange #ff5a00:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "style": "italic",
        "color": "#ff5a00"
    }
}

Text Opacity

The opacity adjusts the text's transparency level, where 1.0 represents full opacity, 0.5 is 50% transparent, and 0 is completely transparent. The default value is 1.0.

For example, to set text opacity to 0.5:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "opacity": 0.5
    }
}

Text Align

The align parameter sets the text's horizontal and vertical alignment within the image. The default alignment is center. Possible values include top, top-right, right, bottom-right, bottom, bottom-left, left, and top-left.

For example, to align text to the top-right:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "align": "top-right"
    }
}

Text Padding

The padding parameter accepts a positive integer and describes the distance in pixels between the text and the image edges. The default value is 0.

For example, to set a text padding of 50 pixels while using a text align of top-right:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "align": "top-right",
        "padding": 50
    }
}

Letter Spacing

The letter_spacing parameter specifies the space between each letter in a block of text, accepting a positive integer. The default value is 0.

For example, to set letter spacing to 15:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "letter_spacing": 15
    }
}

Text Background

The background parameter sets the color of the background placed underneath the text, accepting hex-encoded strings in RGB, RRGGBB, and RRGGBBAA formats.

For example, to set a semi-transparent black background00000080 with a padding of 10:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "background": "00000080",
        "padding": 10
    }
}

Text Border

The border_size and border_color parameters control the border around the text. border_size accepts a positive integer for the border's pixel size, while border_color specifies the border color in RGB, RRGGBB, and RRGGBBAA and formats.

For example, to add a 3-pixel white border (#FFFFFF) to text with orange color (#ff5a00):

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "color": "ff5a00",
        "border_size": 3,
        "border_color": "ffffff"
    }
}

Text Shadow

The shadow_size, shadow_color, and shadow_offset parameters manage the text shadow. shadow_size defines the shadow's pixel size, shadow_color sets the shadow color, and shadow_offset adjusts the distance between the text and its shadow, accepting an array of one or two integers for X and Y offsets. The maximum shadow offset is 10.

For example, to add a 20-pixel black shadow (#000000) with a 10px offset:

{
    "text": {
        "text": "SGVsbG8gV29ybGQK",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "shadow_color": "000000",
        "shadow_size": 20,
        "shadow_offset": [10]
    }
}

Text Break

The break parameter controls the behavior of long text blocks, breaking them into multiple lines by default. Setting break to false forces the text to render in a single line, potentially adjusting the font size.

To demonstrate setting "break": false, consider using a lengthy block of text such as "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua." which is base64-encoded into TG9yZW0gaXBzdW0g.... Here's how you could apply this setting:

{
    "text": {
        "text": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaW5nIGVsaXQsIHNlZCBkbyBlaXVzbW9kIHRlbXBvciBpbmNpZGlkdW50IHV0IGxhYm9yZSBldCBkb2xvcmUgbWFnbmEgYWxpcXVhLgo=",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "break": false
    }
}

Text Width

The width parameter specifies the maximum width of the bounding box within which the text will be rendered on the input image, measured in pixels. This setting helps manage text layout, especially in conjunction with text wrapping and alignment.

For example, to set the maximum width of text to 400 pixels:

{
    "text": {
        "text": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaW5nIGVsaXQsIHNlZCBkbyBlaXVzbW9kIHRlbXBvciBpbmNpZGlkdW50IHV0IGxhYm9yZSBldCBkb2xvcmUgbWFnbmEgYWxpcXVhLgo=",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "width": 400
    }
}

Text Height

The height parameter defines the maximum height of the bounding box for text rendering on the input image. This parameter is crucial for controlling the vertical space that the text occupies, especially when dealing with multiple lines of text or when you want to ensure that the text fits within a specific area.

For example, to set the maximum height of the text to 300 pixels:

{
    "text": {
        "text": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaW5nIGVsaXQsIHNlZCBkbyBlaXVzbW9kIHRlbXBvciBpbmNpZGlkdW50IHV0IGxhYm9yZSBldCBkb2xvcmUgbWFnbmEgYWxpcXVhLgo=",
        "size": 80,
        "weight": "bold",
        "font": "DejaVu Serif",
        "height": 300
    }
}