Render image (v1)

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

This endpoint has been deprecated. Please use Render Image v2 instead.

POST Endpoint

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

Sample request

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

Request body

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

Successful response

Successful response always returns 200 status code, requestId, and href property with url to the rendered result.

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

Error response

Unsuccessful response always returns 400 status code, an error message with details about the error in msg property and status with the HTTP status code.

{
  "msg": "Template not found",
  "status": 400
}

Sample request with metadata

Metadata field allows you to store any JSON object with the generated image.

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

Other possibilities to provide template changes

In some cases providing template changes in the format specified above might not be easy to manage in your code. That is why we provide additional 2 formats to provide template changes.

Simple Array

Changes in changes request body field must be formatted as array and options query parameter must contain USE_SIMPLE_ARRAY value.

Every object of changes field must contain:

• id - component id set it template editor,
• property - component property (eg: text),
• value - component property value

curl
    --location
    --request POST 'https://get.renderform.io/api/api/v1/render?options=USE_SIMPLE_ARRAY' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changes": [
            {
                "id": "my-text-component-id",
                "property": "text",
                "value": "This is my text"
            },
            {
                "id": "my-image-component-id",
                "property": "src",
                "value": "https://my-website.com/image.jpg"
            }
        ]
    }'

Dictionary

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

curl
    --location
    --request POST 'https://get.renderform.io/api/api/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changesDictionary": {
          "my-text-component-id.text": "This is my text",
          "my-image-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).