Batch Processing

Batch processing with Switchboard Canvas lets you send many requests for images to be generation at one time.

Each request in the batch contains overwrites that are used in conjunction with the templates and sizes you specify.

When the batch is complete, a notification is sent as an HTTP POST request to a webhook endpoint that you specify.

The payload sent to the webhook endpoint indicates whether the specific image request was successful, and if so, the URL of the resulting image.

Availability

Batch processing is available on our Agency and Enterprise plans.

Users on the Agency plan can submit batches containing up to 25 requests.

Users on the Enterprise plan can submit batches containing up to 250 requests.

Format of a batch request

A batch request requires two steps:

• A JSON formatted file with one or more collections of element overwrites
• An API request that specifies the template's API name, one or more sizes, and a batchUrl property pointing to the resource from step #1.

{
    "template": "my-quote",
    "sizes": [{
        "width": 500,
        "height": 500
    }],
    "batchUrl": "https://example.com/batch.json",
    "webhook": "https://example.com/webhook"
}

The JSON formatted file containing the overwrites is an array of objects specifying the new values for elements in the template.

Here is an example of a batch request with 3 sets of overwrites:

[
    {
        "quote": {
            "text": "This is a new quote"
        }
    },
    {
        "quote": {
            "text": "Changing the text as well as an image"
        },
        "background": {
            "url": "http://example.com/image.jpg"
        }
    },
    {
        "quote": {
            "text": "That's your best friend..."
        },
        "author": {
            "text": "Fred Durst"
        }
    }
]

In this example, three 500x500 images would be created based on the element overwrites specified. Upon completion, the webhook will receive a POST notification indicating the URLs of the generated images.

Specifying filenames

In batch requests, you can specify output filenames for the images being created.

Depending on the number of size objects being requested, you can include a size{index}filename property that specifies the filename for the corresponding size object.

For example, this batch request will create two images for each record in the batch input file:

{
    "template": "my-quote",
    "sizes": [{
        "width": 500,
        "height": 500
    },
    {
        "width": 800,
        "height": 800
    }
    ],
    "batchUrl": "https://example.com/batch.json",
    "webhook": "https://example.com/webhook"
}

To specify filenames for each image being created, include size{index}filename properties:

[
    {
        "quote": {
            "text": "This is a new quote"
        },
        "size1filename": "new-quote500x500.png",
        "size2filename": "new-quote800x800.png"
    },
    {
        "quote": {
            "text": "This is the old quote"
        },
        "background": {
            "url": "http://example.com/image.jpg"
        },
        "size1filename": "old-quote500x500.png",
        "size2filename": "old-quote800x800.png"
    }
]