POST /

Creates images based on the template and overwrites detailed in the body of the request.

Authorization

To authorize your requests to Switchboard Canvas, you'll need your API key. Your API key can be found in the top-right corner on the main Templates page, after you sign in at Switchboard. Add your API key to the Headers collection of your request:

X-API-Key: <your API key>

Request Format

All available options

{
    "template": "template-api-name",
    "sizes": [
        {
            "width": 1080,
            "height": 1080,
            "elements": {
                ...
            }
        },
        {
            ...
        }
    ],
    "elements": {
        "image-element": {
            "angle": 45,
            "backgroundColor": "#FF0000",
            "backgroundOpacity": 0.5,
            "contain": true,
            "cornerRadius": 20,
            "fill": true,
            "fillColor": "#0000FF",
            "horizontalAlignment": "left",
            "lut": "https://example.com/effect.lut",
            "opacity": 0.5,
            "qrCode": "A value to be encoded in the QR code image",
            "url": "https://example.com/image.jpg",
            "verticalAlignment": "top",
        },
        "text-element": {
            "angle": 45,
            "fillTextBox": true,
            "horizontalAlignment": "left",
            "minimumFontSize": 65,
            "opacity": 0.5,
            "text": "This is some text",
            "textBackgroundColor": "#00FFFF",
            "textBackgroundHeight": 0.5,
            "textBackgroundPadding": 50,
            "textColor": "#FFFFFF",
            "textHighlightColor": "#00FF00",
            "textLetterSpacing": -250,
            "translateTo": "it",
            "verticalAlignment": "top"
        },
        "rectangle-element": {
            "angle": 45,
            "opacity": 0.5,
            "fillColor": "#0000FF",
            "strokeColor": "#000000",
            "strokeWidth": 20,
            "backgroundTransparent": true
        }
    }, 
    "url": "https://example.com/blog-post.html",
    "batchUrl": "https://example.com/batch-data.json",
    "webhook": "https://example.com/webhook",
    "airtableApiKey": "airtable-api-key",
    "tweet":
        "https://twitter.com/switchboardai/status/1442852092159217668",
    "updateTwitterHeader": true
}

Basic request

The minimum valid request comprises a JSON object consisting of a template property and a sizes array, which contain objects of width and height numeric pairs.

{
    "template": "template-api-name",
    "sizes": [
        {
            "width": 1080,
            "height": 1080
        }
    ]
}

Specifying overwrites

Overwrites are how your images become dynamic. You can specify property values to replace the values in your template. This is achieved using the elements object.

{
    "template": "template-api-name",
    "sizes": [
        {
            "width": 1080,
            "height": 1080
        }
    ],
    "elements": {
        ...
    }
}

In the elements object, you can specify elements used in the template, their properties, and new values. Images will be created by applying your overwrite values to the values you defined in your template.

In this example, we're specifying new text to replace the text in the quote element in the template.

{
    "template": "quote",
    "sizes": [
        {
            "width": 1080,
            "height": 1080
        }
    ],
    "elements": {
        "quote": {
            "text": "A problem shared is a problem havled."
        }
    }
}

Multiple Images

Switchboard Canvas supports creating multiple images from a single API call. As Switchboard Canvas templates are responsive, you can design one template and generate images from it for a variety of purposes or destinations.

{
    "template": "quote",
    "sizes": [
        {
            "width": 1080,
            "height": 1080
        },
        {
            "width": 1080,
            "height": 1920
        }
    ]
}

Futhermore, overwrites can be specified either at the individual size level or at the template level.

{
    "template": "quote",
    "sizes": [
        {
            "width": 1080,
            "height": 1080,
            "elements": {
                "quote": {
                    "text": "This image is square."
                }
            }
        },
        {
            "width": 1080,
            "height": 1920,
            "elements": {
                "quote": {
                    "text": "This image is sized for an Instagram story."
                }
            }
        }
    ]
}

You can also mix and match overwrites and the individual size level and the template level.

{
    "template": "quote",
    "sizes": [
        {
            "width": 1080,
            "height": 1080,
            "elements": {
                "quote": {
                    "text": "This image is square."
                }
            }
        },
        {
            "width": 1080,
            "height": 1920
        }
    ],
    "elements": {
        "backdrop": {
            "url": "https://images.com/landscape.jpg"
        }
    }
}

Errors

Sending an invalid API Key, or not sending one at all, will result in a 403 Forbidden response.

Error and Warning Responses

Switchboard Canvas will generate a detailed error report if for any reason an image cannot be generated.

Where URLs are specified in Image element overwrites for example, and those request fail, a warning is generated and included in the response. However, the image continues to generate in this case.

Warnings may be found at the request level and also at the individual size level.

200 Response

{
    "duration": 2050,
    "usage": true,
    "success": true,
    "warnings": [

    ],
    "sizes": [
        {
            "size": {
                "width": 1080,
                "height": 1080
            },
            "warnings": [
            ],
            "success": true,
            "url": "https://files.canvas.switchboard.ai/..."
        }
    ]
}

Check the success for each size in the sizes array and retrieve the url value to access the generated image. Switchboard Canvas images are available for 7 days at the given URL.