Video API reference

Robolly features a flexible video API that enables you to create personalized videos in large quantities automatically. The Robolly video API works based on Robolly dynamic templates. Create videos with natural animations based on real-world physics, multiple clip support, video in video support, audio, high FPS, high definition resolution, and all other features available from our template editor like smart cover. To start with the video API, you need a Robolly account.

Available endpoints:

Authentication

Robolly API key must be included in the authorization header:

Authorization: Bearer {ROBOLLY_API_KEY}

Parameters

Timeline object

Modification object

Audio object

Example

An example on how to queue a 3 clip video with background music for a render via Robolly API. TIP: Use the Movie page at the Robolly dashboard to help you create the JSON payload data. Here's the request JSON payload:

{
	"audio": [
        {
            "src": "https://file-examples.com/storage/feaade38c1651bd01984236/2017/11/file_example_MP3_700KB.mp3",
            "volume": 0.7,
        }
    ],
	"timeline": [
		{
			"templateId": "123",
			"duration": 5000,
			"modifications": [
				{
					"value": "https://images.unsplash.com/photo-1491067852826-a60f365ff611?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=2000",
					"target": "image"
				},
				{
					"value": "breakingnews.com",
					"target": "website"
				},
				{
					"value": "Texas falls outside preseason college football rankings despite first-place vote in coaches poll",
					"target": "title"
				},
				{
					"value": "Daryl Lyon",
					"target": "uptitle"
				},
				{
					"value": "Sport",
					"target": "category"
				}
			]
		},
		{
			"templateId": "123",
			"duration": 5000,
			"modifications": [
				{
					"value": "https://images.unsplash.com/photo-1518183214770-9cffbec72538?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=2000",
					"target": "image"
				},
				{
					"value": "breakingnews.com",
					"target": "website"
				},
				{
					"value": "Here’s what investors should do as the housing market faces tough times",
					"target": "title"
				},
				{
					"value": "Cyan Hendry",
					"target": "uptitle"
				},
				{
					"value": "Finance",
					"target": "category"
				}
			]
		},
		{
			"templateId": "124",
			"duration": 5000,
			"modifications": [
				{
					"value": "Visit our website to read more.",
					"target": "title"
				},
				{
					"value": "breakingnews.com",
					"target": "uptitle"
				}
			]
		}
	]
}

In a response, Robolly will include the ID of the render and a resourceUrl which you can periodically call to check the status of the video. We recommend to save the video render ID or the resourceUrl on your side for later use (so you can get the file URL after rendering is done). Here's an example of a typical response:

{
    "status": "queued",
    "id": "1526e51daaa23s6450s170g9",
    "renderCostApprox": 250,
    "renderCreditsLeft": 986599,
    "resourceUrl": "https://api.robolly.com/v1/renders?id=1526e51daaa23s6450s170g9"
}

Calling the resourceUrl will return the data about the video render. It's recommended to periodically call resourceUrl to check the status of the render and to get a fileUrl. Here's an example of a typical JSON response:

{
    "hasMore": false,
    "paginationCursorNext": null,
    "paginationCursorPrevious": null,
    "value": [
        {
            "id": "1526e51daaa23s6450s170g9",
            "organizationId": "666e51daaa23s6450s170f0",
            "templateId": "64f99dd328a32b6ed8fd5a25",
            "cacheHash": null,
            "modifications": [],
            "createdAt": "2023-10-11T17:02:21.377Z",
            "size": 594944,
            "width": 1080,
            "height": 1080,
            "formatType": "mp4",
            "timemark": 16.01,
            "fileName": "1526e51daaa23s6450s170g9",
            "assetsLoaded": [],
            "hits": 0,
            "status": "done",
            "timeline": [
                // your timeline items...
            ],
            "audio": [
                // your audio items...
            ],
            "renderCost": 250,
            "file": "{HERE_WILL_BE_VIDEO_FILE_URL_WHEN_DONE}",
            "preview": "{HERE_WILL_BE_VIDEO_THUMBNAIL_URL_WHEN_DONE}"
        }
    ]
}

Webhooks

Alternatively, you can use webhooks to get notified when the video render is done. Register a webhook by providing a webhookUrl into the render video API request. Note that Robolly will attempt the webhook request only once. Here's an example:

{
	"webhookUrl": "https://myapp.com/robolly-webhook-handler",
	"timeline": [
		{
			"templateId": "123",
			"duration": 5000,
			"modifications": [
				{
					"value": "Texas falls outside preseason college football rankings despite first-place vote in coaches poll",
					"target": "title"
				},
			]
		}
	]
}

Webhook JSON payload

Verify the legitimacy of the webhook request by checking the robolly-secret header against your Robolly API key.

{
    "type": "render.done",
    "data": {
		"time": "2020-11-07T09:50:09.951Z",
        "render": {
            "id": "123",
            "resourceUrl": "https://api.robolly.com/v1/renders?id=123",
			"file": "https://robolly.s3.eu-central-1.amazonaws.com/123",
            "preview": "https://robolly.s3.eu-central-1.amazonaws.com/123",
            "createdAt": "2020-11-07T09:50:09.951Z",
        },
    }
}

Node.js webhook handler example

function handleSidemailWebhook(req, res, next) {
	// Verify that the request is coming from Sidemail
	if (req.headers["robolly-secret"] !== ROBOLLY_API_KEY) {
		return res.status(401).send();
	}

	// Your custom logic ...
	console.log(req.body.type, req.body.data);

	// Acknowledge the webhook by responding with 200 status code
	return res.status(200).send();
}