Table of content

General
API

Render image

Last modified: April 15, 2022Author: Jakub Pomykała

This endpoint allows you to generate images based on a template created in Template Editor.

POST Endpoint

https://get.renderform.io/v1/render

Sample request

curl 
    --location 
    --request POST 'https://get.renderform.io/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changes": [
            {
              "id": "text_1f",
              "color": "#eeeeee",
              "text": "Hello There!",
            },
            {
              "id": "image_6g",
              "src": "https://jpomykala.com/assets/me-2019.jpeg"
            }
        ],
        "metadata": {
          "my-key": "my value"
        }
    }'

Request body

  • template (required) - template identifier,
  • changes (optional) - override component properties for given template,
  • expires (optional) - link expiration time in seconds, available values from 1 to 604800
  • webhookUrl (optional) - send response to the given URL as a POST request.
  • metadata (optional) - any JSON object, can be used as metadata container

Read more about webhooks.

Successful response

{
  "requestId": "febbd34c-cadf-43e6-926c-5942016aea4e",
  "href": "https://cdn.renderform.io/.../febbd34c-cadf-43e6-926c-5942016aea4e.jpg"
}

Format options

You can use a different formats to apply changes in to create your image from template.

Array

Changes in changes request body field must be formatted as array.

Every array object must contain properties:

  • id - component id set it template editor,
  • property - component property (eg: text),
  • value - component property value
"template": "my-template-id",
"changes": [
    {
        "id": "my-component-id",
        "property": "text",
        "value": "This is my text"
    },
    {
        "id": "my-component-id",
        "property": "src",
        "value": "https://my-website.com/image.jpg"
    }
]

Dictionary

Some integrations (eg: Zapier) doesn't allow providing arrays of objects, for such cases applying changes as dictionary may be a better way of integration.

Changes in changesDictionary request body field must be formatted as key-value object.

"template": "my-template-id",
"changesDictionary": {
  "my-component-id.text": "This is my text", 
  "my-component-id.src": "https://my-website.com/image.jpg", 
}

Please note that in dictionary format, your component id cannot contain a dot . because RenderForm won't be able to process your request correctly.

GET Endpoint

https://get.renderform.io/img/TEMPLATE_ID.jpg?componentId.property=value&apiKey=API_KEY

Use Query String notation in order to provide changes.

Sample request

https://get.renderform.io/img/MY_TEMPLATE_ID.jpg?title.text=Hello!&avatar.src=example.com/me.jpg&apiKey=MY_API_KEY

Please note that only the first change element is separated with ? (question mark) and all other changes must be separated with & (ampersand).