Automator

Start creating videos through the API

Both the creation of videos through the API and the creation of projects through the API, begin by having a template to start from. Lots of templates are made available for you but you can of course create your own as well. On this page we will assume you already have a template that you want to create a video (or project) from. If this is not the case, go check out our tutorial on how to create templates.

All API calls need to be authenticated with an access token. To generate an access token, head to our Developer Portal and use the token as a bearer token in the Authentication header of each API call.

curl --header 'Authorization: Bearer <your access token>'

Each render will cost you one of your credits. Your amount of available credits can be found on the dashboard under your profile.

To read more about credits, check out our FAQ.

When you run out of credits, you'll get the following response from us when trying to create a video:

{
    "message": "You have exceeded the maximum number of renders included in your contract. Please contact our sales team to increase your render package.Optionally you can ask our Sales team to enable surcharging, which will allow you to create renders on demand, and will be billed monthly",
    "key": "error.generator_contract_exceeded"
}

All template fields that can be used during your (automated) video creation have a uuid that you'll need to reference to when creating a video from your template. Therefore you need to know where to find the uuids for those variables. You'll get the variables when you fetch the details of your template based on your template uuid (which you can find in the url bar of your browser when in the dashboard, or through a call to GET https://api.moovly.com/generator/v1/templates).

In the response, you'll find an array property variables that contains the list of all variables that can be changed during the creation of your video. Here, two properties of each variable are most important: the id (uuid) and the type.

{
    "id": "TemplateID",
    "name": "Template Name",
    "duration": 52,
    "thumb": "https://assets.moovly.com/uploads/images/thumbnail.png",
    "preview": "https://renders.moovly.com/templatepreview.mp4",
    "original_moov_id": "f1f25560-b11b-11ec-b909-0242ac120002",
    "original_project_id": "f1f25560-b11b-11ec-b909-0242ac120002",
    "public": false,
    "category": "template-category",
    "tags": [
        "Announcement"
    ],
    "variables": [
        {
            "id": "265b79e1-a888-11ec-afbd-0afd511c093b",
            "name": "Template text",
            "weight": 1,
            "type": "text",
            "identifier": "OptionalIdentifier",
            "requirements": {
                "multiline": false,
                "maximum_length": 100,
                "minimum_length": 1
            },
            "default": "Test",
            "clip_id": "00868ea0fef997ed42a6"
        }
    ],
    "archived": false,
    "created_by": "1094311454",
    "template_settings": {
        "changeableColors":  ["#D8321A", "#FFCC00"],
        "changeableFonts": ["Lato"]
    },
    "created_at": "2022-03-20T19:58:45+00:00",
    "quick_editable": true,
    "allow_updates": true,
    "shares": [],
    "owner": "88fc88d6-b11c-11ec-b909-0242ac120002",
    "has_comments": false,
    "json": [PROJECT_JSON]
}

template_id

required, string

The id of the template you want to use. This can be retrieved from the url bar in the dashboard or from the GET https://api.moovly.com/generator/v1/templates call.

options

required, object

A collection of options that can be given to the api

  • quality: default, 480p, 720p or 1080p. Defines the quality of your video, and hence only applicable when creating a video.
  • create_render: boolean that specifies whether a video has to be created.
  • create_project: boolean that specifies whether a project has to be created.
{
	"quality": "480p",
    "create_render": true,
    "create_project": false
}

values

required, array of objects

It is possible to create multiple videos from a template in a single API call. Therefore this values property is an array with one object per requested video. Usually it makes more sense to make one API call per video you want to create. Hence, the array usually contains only one object.

The object should contain the variable ids or identifiers and their desired values in the template_variables property. Additionally, an external reference to your own system can be provided in the external_id property for administrative purposes.

There are 2 ways to assign variables to a value:

  • The first way is to work with the variable id that you can find in the template response. (See an example here).
  • The second way is to work with identifiers, identifiers is a self-chosen string that you assign in the editor (object => template => unique identifier).
[
    {
        "external_id": "ref-or-id-to-your-own-system",
        "template_variables": {
            "6d31e5ea-ba36-11ec-afbd-0afd511c093b": "my text",
            "WebsiteUrlIdentifier": "https://www.site.com/example.jpg",
            "7bd53f83-d43a-4771-a4a8-3e8bfd4fce3a": "https://www.site.com/example.mp3",
            "845dae57-03cb-464a-bcc6-a591859a5686": "https://www.site.com/example.mp4"
        }
    }
]

Currently we support four different types of template variables:

  • Text
  • Image
  • Video
  • Sound

Text

For basic text replacement, you can put your text in the value.

{
    "external_id": "ref-or-id-to-your-own-system",
	"5c7d3d8b-0f78-416d-a3f5-2568c2341a73": "This is a text field"
}

In case you want to replace your text in a more advanced way, you can also add basic HTML in your field. But instead of passing a string, you now need to provide an object with a property type set to rich-text and a property value that contains text with optional HTML formatting.

Be aware that this not only gives you a lot of flexibility, but also an easy way to break your video. So be careful with this usage. Supported tags are

  • <i>text</i> for italic text,
  • <b>text</b> for bold text,
  • <br/> for a line break,
  • <li>text</li> for a list item,
  • <color value="red">text</color> for coloured text.
{
    "external_id": "ref-or-id-to-your-own-system",
	"5c7d3d8b-0f78-416d-a3f5-2568c2341a73": {
    	"type": "rich-text",
        "value": "Wow <i>this</i> <b>is</b> a <color value=\"#0000FF\">super</color> cool <li>feature</li>"
    }
}

To replace an image or video in your video you can either use the url of a public accessible file or pass an object id of one of your assets.

Supported image types are GIF, JPEG, JPG, PNG, SVG, WEBP and HEIC. Supported video types are MP4, MKV, FLV, WMV, M4V, MPEG, AVI, WEBM, MOV and 3GP.

To get the id of an asset, you can follow this guide. Using your assets instead of public accessible files will be faster, because we do not need to process your file. If speed is important we advise the second option.

{
    "external_id": "ref-or-id-to-your-own-system",
    "template_variables": {
        "0eabf9d2-7bdd-47a0-8b28-9464d757232c": "https://www.site.com/example.jpg",
        "0eabf9d2-7bdd-47a0-8b28-9464d757232c": "N9KB2kXaA8wB1jBgnjWV6Rqx",
        "845dae57-03cb-464a-bcc6-a591859a5686": "https://www.site.com/example.mp4"
    }
}

Sound is handled similarly to images and video. You either provide a url to a public accessible file or you specify an asset id. Supported file types are FLAC, M4A, MP3, WAV, OGG, WMA, AIFF and OPUS.

An extension to basic sound variables though, is the Text-To-Speech (tts) service. To make use of it, you'll need to provide an object for your template variable instead of a basic url reference to your file.

Available providers are AWS and Google. Sample voices can be found on this page. For both providers, the value and the voice properties are required. For AWS, the engine and language_code are required as well.

An AWS example looks like:

{
    "external_id": "ref-or-id-to-your-own-system",
    "template_variables": {
        "3cd44862-76e9-4df3-a8bc-39a91b8d966e": {
            "type": "tts",  
            "value": "This is text that will be converted into speech.",
          	"identifier": "aws;Kevin;Male;en-US;neural;normal"
        }
    }
}

A Google example looks like:

{
    "external_id": "ref-or-id-to-your-own-system",
    "template_variables": {
        "3cd44862-76e9-4df3-a8bc-39a91b8d966e": {
            "type": "tts",
            "value": "This is text that will be converted into speech.",
            "identifier": "google;en-US-Wavenet-H;Female;en-US;none;none"
        }
    }
}

modifications

change fonts & colors

It is possible to change the fonts and colors of a template video. You can change fonts and colors by adding modifications in the value entry. See example request:

"values": [
    {
        "external_id": "ref-or-id-to-your-own-system",
        "template_variables": [TEMPLATE_VARIABLES],
		"modifications":{
			"colors": {
				"#D8321A": "#DC1964"
				"#FFCC00": "#232D64"
			},
			"fonts": {
				"Lato": "Arial"
			}
		}
    }
]

In the Editor under global tab => template, you can choose the colors and fonts that can be changed in a template video, after you specify those and save the template. These modifications are also returned from the template response as template_settings, see the template response example here

Once you specified the changeable fonts and colors in the editor. You can change the color or font by specifying the current value as object key and the new value as object value see:

"fonts": {
 "$templateFont": "$fontToBe"
},
"colors": {
 "$templateColor": "$colorToBe"
}

notifications

not required

Notifications are there to inform you when the creation of your video is finished. We support multiple channels and they can be combined in case you want to be notified on more than one channel.

We support following types:

  • Callback
  • Upload to Youtube
  • Upload to Google Drive
  • Upload to Instagram
  • Email
{
    "notifications": [
        {
            "type": [ "callback", "upload-youtube", "upload-google-drive", "email" ],
            "payload": { ... }
        }
    ]
}

The callback notification has a required url property and will make an HTTP POST call towards the url you provide.

{
    "type": "callback",
    "payload": {
        "url": "https://www.site.com/callback"
    }
}

On successful creation of your video, we will let you know via an HTTP POST call with a json body like:

{
    "resource": {
        "id": "c0e4e6ba-9210-4994-b0f6-ab9faf94a43e",
        "job_id": "3bedfaaf-93aa-4fd0-ad80-059f25a2993b",
        "template_id": "547ca151-a438-11ec-afbd-0afd511c093b",
        "external_id": "your-ref-to-campaign",
        "status": "success",
        "title": "",
        "error": null,
        "project_id": null,
        "moov_id": null,
        "thumbnail": "https://.../92bba51.png",
        "url": "https://.../92bba519020video.mp4"
    },
    "resource_type": "render"
}

In the unfortunate event that something goes wrong during the creation of your video, you'll also receive a callback from us.

This notification immediately uploads your video to Youtube when the creation of it is finished. For this to work though, your Moovly account has to be linked to your Youtube account. You can do this in the integration window in our dashboard.

A title and description property are required while a playlist_id is optional. Additionally we support an extra (optional) callback property to let you know when the upload to youtube has finished.

{
    "type": "upload-youtube",
    "payload": {
        "title": "My title",
        "description": "Nice video, thanks Moovly!",
        "playlist_id": "OPTIONAL PLAYLIST ID",
        "callback": "https://www.site.com/optional-callback"
    }
}

If a callback url is provided, we'll let you know with an HTTP POST call and following json body. Which allows you to extract the Youtube id of the newly uploaded video:

{
    "external_id": "your-ref-to-campaign",
    "type": "render",
    "status": "success",
    "payload": {
        "video_id": "jG4JNpRYMr0"
    },
    "error": null
}

This notification immediately uploads your video to Google Drive when the creation of it is finished. For this to work though, your Moovly account has to be linked to your Google account. You can do this in the integration window in our dashboard.

The title property will be the file name of your video and the path property is the name of the folder you want to upload to. That name can be found in the url bar of your browser when you visit your Google Drive.

{
    "type": "upload-google-drive",
    "payload": {
        "title": "Video title",
        "path": "1McLVYFXx4zRatLOkNp7q8etYlgZoi3uQ"
    }
}

This notification immediately uploads your video to your Instagram account when the creation of it is finished. For this to work though, your Moovly account has to be linked to your Instagram account. You can do this in the integration window in our dashboard.

{
    "type": "instagram",
    "payload": {
        "instagram_business_account_id": "17841454046281825",
        "caption": "your caption"
    }
}

The email notification type sends you an email when your video is created. The email will contain a link to your video so you can download it.

The only required payload property is email. But the email can optionally be tweaked with a subject, a message and/or a logo.

{
    "type": "email",
    "payload": {
        "email": "your.email@site.com",
        "subject": "New video",
        "message": "New video is ready.",
        "logo": "https://www.site.com/logo.jpg"
    }
}
{
    "template_id": "4375d09a-a2da-44d2-b368-e0b2bbd2f971",
    "options": {
        "quality": "1080p",
        "create_render": true,
        "create_project": false
    },
    "values": [
        {
            "external_id": "your-reference-1",
            "title": "Custom project title here",
            "template_variables": {
                "3cd44862-76e9-4df3-a8bc-39a91b8d966e": "Text value here",
                "0ec3a816-0df7-40fe-8f7c-d57e285aabb7": "https://dummy.png",
                "fc413f91-2ab8-4ecd-aef7-859c314afb52": "lA6Pxe4J89wedmlE39bD72Rp"
            }
        }
    ],
    "notifications": [
        {
            "type": "callback",
            "payload": {
                "url": "https://example.com/callback-endpoint"
            }
        },
        {
            "type": "upload-youtube",
            "payload": {
                "title": "Video title",
                "description": "Test description\nThis video was generated by the Moovly Automator. https://www.moovly.com",
                "playlist_id": "QL7zkj_vV4ErDa894sk5e_a6edWvVc3G8b",
                "callback": "https://example.com/youtube-callback-endpoint"
            }
        },
        {
            "type": "upload-google-drive",
            "payload": {
                "title": "Video title",
                "path": "3zqFRJT1wsfMqHbqJFBWHgEa3s5jLFzD7"
            }
        }
    ]
}