Creatomate
API & Integration -> API Reference

Create a Render

This API endpoint allows you to create a video, image, or GIF, which is also referred to as a Render.

Send a POST request to https://api.creatomate.com/v2/renders with the parameters below as a JSON body, using your project's API key.

Parameters

template_id string optional

The ID of the template created in the editor. If you don't want to use a template, you can omit this parameter and provide RenderScript directly in the API request.

modifications object optional

Changes to apply to the template before it is rendered. Learn more about modifications on this page.

render_scale number optional

The scale at which to render. The default value is 1 (100%), which means the output is generated at the template's resolution; 0.5 renders at half the width and height. No range is enforced, but the output never exceeds 3840 pixels on either side, and the free plan has a lower cap, stated under Limits and concurrency: a scale that would exceed the cap is lowered to it.

max_width number optional

Scales the output so that its width never exceeds the provided number. This parameter can be combined with max_height. If set, render_scale is ignored.

max_height number optional

Scales the output so that its height never exceeds the provided number. This parameter can be combined with max_width. If set, render_scale is ignored.

webhook_url string optional

A URL that is called when the render succeeds or fails.

metadata string optional

A value you want to pass to the webhook URL.

curl -X POST https://api.creatomate.com/v2/renders \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     -d '{
  "template_id": "YOUR_TEMPLATE_ID_HERE",
  "modifications": {
    "Text-1": "This text is placed in the element Text-1",
    "Video-1": "https://cdn.creatomate.com…/demo/video1.mp4"
  },
  "render_scale": 0.75,
  "max_width": 1080,
  "max_height": 1080,
  "webhook_url": "https://example.com…/webhook",
  "metadata": "Any text value"
}'

Response

On success, the endpoint responds with 202 Accepted and the new render as a single object, structured as described on What is a render?. Its status starts at planned. The url already says where the file will be, but only links to the finished file once the status is succeeded.
The response may also carry errors and warnings, two arrays of strings about your request. errors describe problems that will make the render fail, such as a value outside its range; warnings point at parts that are ignored, such as a modification whose name matches no element in the template. Neither stops the render: read them and fix the request.
A malformed request is answered with 400 Bad Request and a hint that says what to fix, for example a missing template_id or one that is not a valid template ID. The error format is described on the REST API page.
{
  "id": "a862048b-d0dc-4029-a4ef-e172e8ded827",
  "status": "planned",
  "url": "https://cdn.creatomate.com/renders/a862048b-d0dc-4029-a4ef-e172e8ded827.mp4",
  "template_id": "YOUR_TEMPLATE_ID",
  "output_format": "mp4",
  "render_scale": 0.75,
  "modifications": { … },
  "webhook_url": "https://example.com/webhook",
  "metadata": "Any text value"
}

Examples

See the examples below to get started using this API endpoint.
Template-based Rendering
→

This example shows how to generate a video based on a template.

Using RenderScript
→

If you prefer not to use a template, you can pass the RenderScript data directly.

Related resources