Templates API

This chapter explains how to manage templates using the Plainly API. A template defines how After Effects layers in your project become set of parameters that can be supplied when triggering renders, as well as what composition is being rendered.

Template lifecycle

There is no concept of an independent Template object, they are rather contained within a Project object. Thus, they share the same lifecycle as projects. In general, operations on templates can be done once the project is successfully analyzed.

At least one template in a project is marked as default, which is used when no specific template is specified during rendering.

Creating a template

There are two main ways to create templates:

• Auto-generate – Automatically generate a template based on the After Effects project structure and a simple input. Simple
• Manual creation – Define a template explicitly using its JSON definition. Advanced

No matter which method you choose, the JSON response you get back will contain the ID of the new template. You can always use this ID to execute a GET request to /api/v2/project/{projectId}/templates/{templateId} to obtain information about the template

Auto-generate

The auto-generation feature allows you to quickly create a template without needing to manually define each parameter. It works by using one of the two available types of auto-generation:

1. All – allows you to create a dynamic render parameter in a template for every layer in the target render composition.
2. Prefix – allows you to specify a prefix that will be used to filter layers, thus targeting only those layers that match the prefix.

Call POST /api/v2/projects/{projectId}/templates/auto-generate and provide the body with the desired type and options. For example, to create a template parameterizing all layers in the “Main” composition:

curl -X POST "https://api.plainlyvideos.com/api/v2/projects/$PROJECT_ID/templates/auto-generate" \
	-u "$PLAINLY_API_KEY:" \
	-H "Content-Type: application/json" \
	-d '{
		"type": "all",
		"targetCompositionName": "Main",
		"allLayers": true
	}'

You can control which layers are included by mixing different available options. See Templates API reference  for details.

Manual template creation

In order to create a template manually, you need to define its complete structure in JSON format. However, in order to correctly target a rendering composition and map After Effects layers to parameters, you need to know the names and IDs of compositions and layers in a project.

This is where project metadata is useful. You can retrieve the project metadata which returns a JSON object containing all compositions and their layers.

The first step is to define a target rendering composition, which is done by referencing composition name and ID in the create template POST /api/v2/projects/{projectId}/templates request. Note that the name and ID must match a composition in the project metadata.

curl -X POST "https://api.plainlyvideos.com/api/v2/projects/$PROJECT_ID/templates" \
	-u "$PLAINLY_API_KEY:" \
	-H "Content-Type: application/json" \
	-d '{
		"name": "My Template",
		"renderingComposition": "Main",
		"renderingCompositionId": 1,
		"layers": []
	}'

Then, you can define the layers that will be used as parameters in the template. The example below defines that a single layer will be changed during rendering:

• It’s a media layer with layerName and internalId taken from the project metadata.
• The compositions defines where is this layer contained, in this case the “Main” composition with ID 1.
• The label is a human readable name for this dynamic parameter.
• And finally the parametrization object defines how the layer will be parametrized. In this case, it uses an expression to reference a variable called logo. All variables must be prefixed with #.

curl -X POST "https://api.plainlyvideos.com/api/v2/projects/$PROJECT_ID/templates" \
	-u "$PLAINLY_API_KEY:" \
	-H "Content-Type: application/json" \
	-d '{
		"name": "My Template",
		"renderingComposition": "Main",
		"renderingCompositionId": 1,
		"layers": [
			{
				compositions: [
					{
						"name": "Main",
						"id": 1
					}
				],
				"internalId": "2",
				"layerName": "Media	Layer",
				"layerType": "MEDIA",
				"mediaType": "image",
				"label": "Main image",
				"parametrization": {
					"expression": true,
					value: "#logo"
				}
			}
		]
	}'

When rendering you supply a value for logo parameter. The API supports other layer types, effects and scripting as well. Refer to the Templates API reference  for the complete schema.

Default rendering options

When creating a template, you can also specify default rendering options which define settings that will be applied to all renders using this template.

The options can also be updated once the template is created using a call to POST /api/v2/projects/{projectId}/templates/{templateId}/options:

curl -X POST "https://api.plainlyvideos.com/api/v2/projects/$PROJECT_ID/templates/$TEMPLATE_ID/options" \
	-u "$PLAINLY_API_KEY:" \
	-H "Content-Type: application/json" \
	-d '{
		"outputFormat": {
			"postEncoding": {
				"type": "smallest"
			}
		},
		"webhook": {
			"url": "https://example.com/render-callback"
		}
	}'

Additional operations

You can also perform the following operations related to templates using the API:

• Update template  – Modify an existing template by changing its name, rendering composition, or layers.
• Clone template  – Create a copy of an existing template, which can be useful for creating variations.
• Set default  – Mark a template as the default for the project.
• Delete template  – Remove a template from the project.

Best practices

• Metadata is crucial – Always retrieve the project metadata before manually creating or updating templates. This ensures you have the correct names and IDs for compositions and layers.
• Unexpected results – If your rendered video doesn’t match expectations, inspect the parameter values you sent and retrieve the template to verify layer mappings.