Plainly Videos

https://help.plainlyvideos.com/docs
Admin
Plainly Videos is an automated video rendering platform that transforms After Effects templates into...
Tokens:90,728
Snippets:466
Trust Score:8.9
Update:11 months ago
Show doc for...
Tokens:
Raw
### Project Creation JSON Response Example

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

This is an example JSON response received after successfully creating a project. It includes details like the project's name, ID, size, upload status, analysis status, and other metadata.

```json
{
	"name": "My Project",
	"id": "00000000-acf3-4d3e-bb48-07036d023220",
	"size": 32235740,
	"attributes": {
		"tags": []
	},
	"lastModified": "2025-07-30T11:07:02.309Z",
	"description": "This is my project description",
	"sharingLinks": null,
	"createdBy": null,
	"createdDate": "2025-07-30T11:07:02.309Z",
	"revisionHistory": null,
	"sharing": null,
	"aeVersion": "AE2025",
	"defaultTemplateId": null,
	"templates": [],
	"uploaded": true,
	"analyzed": false,
	"strictFontChecks": null,
	"analysis": {
		"pending": false,
		"done": false,
		"failed": false,
		"error": null,
		"upgradeError": null
	}
}
```

--------------------------------

### API Versioning

Source: https://help.plainlyvideos.com/docs/developer-guide/authentication-and-setup

Information about API versioning in the Plainly API and how breaking changes are managed.

```APIDOC
## API Versioning

### Description
The current API is versioned under `/api/v2/`. While backward compatibility is maintained, minor breaking changes may occasionally occur.

### Breaking Changes
When a breaking change is introduced, a migration period will be provided to allow users to update their implementations accordingly.
```

--------------------------------

### Rate Limiting

Source: https://help.plainlyvideos.com/docs/developer-guide/authentication-and-setup

Details about the rate limits imposed by the Plainly API and how to handle exceeding them.

```APIDOC
## Rate Limiting

### Description
Each organization is limited to 400 requests per minute on average, with bursts up to 600 requests allowed in a single minute.

### Exceeding Limits
When the rate limit is exceeded, the API returns `429 Too Many Requests` along with a `Retry-After` header indicating when to retry.

### Recommendation
Implement retry logic in your integration to handle rate-limiting responses gracefully.
```

--------------------------------

### Example error response payload

Source: https://help.plainlyvideos.com/docs/developer-guide/authentication-and-setup

Shows a typical JSON error payload returned by the API when a request fails, including timestamp, HTTP status, error type, descriptive message, and request path. Useful for implementing error handling and logging.

```JSON
{
    "timestamp":2025-07-29T11:39:50.490+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "The project with the id 9924184e-f777-4768-a99b-dde9b90dc0bb does not exist.",
    "path": api/v2/renders"
}
```

--------------------------------

### Error Handling

Source: https://help.plainlyvideos.com/docs/developer-guide/authentication-and-setup

Explains how errors are structured in responses from the Plainly API and lists common HTTP status codes with their meanings.

```APIDOC
## Error Handling

### Description
When an error occurs, the response body typically includes two fields: `message` and `error`. In many cases, the `X-PlainlyErrorCode` header is also included.

### Common HTTP Errors
| Code | Name | Description |
|------|------|-------------|
| `400` | Bad Request | The request was malformed or contained invalid parameters. |
| `401` | Unauthorized | The API key is missing or invalid. |
| `403` | Forbidden | The key does not have permission for the requested operation. |
| `404` | Not Found | The requested resource does not exist. |
| `429` | Too Many Requests | Rate limit exceeded. |
| `500` | Internal Server Error | An issue occurred on Plainly’s side. |

### Error Response Example
```
{
  "timestamp": "2025-07-29T11:39:50.490+00:00",
  "status": 404,
  "error": "Not Found",
  "message": "The project with the id 9924184e-f777-4768-a99b-dde9b90dc0bb does not exist.",
  "path": "/api/v2/renders"
}
```
```

--------------------------------

### Create Project via ZIP Upload - cURL Example

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

This example demonstrates how to create a new project by uploading a local ZIP file using `curl`. It utilizes the `POST /api/v2/projects` endpoint with `multipart/form-data` encoding, including the ZIP file and optional project name and description.

```shell
curl -u "$PLAINLY_API_KEY:" \
     -F file=@my_project.zip \
	 -F name="My Project" \
	 -F description="This is my project description" \
     https://api.plainlyvideos.com/api/v2/projects
```

--------------------------------

### Create Project from URL - cURL Example

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

This example shows how to create a new project by providing a public URL to a ZIP file using `curl`. The `POST /api/v2/projects` endpoint is used with `multipart/form-data`, specifying the `fileUrl` along with optional project `name` and `description`.

```shell
curl -u "$PLAINLY_API_KEY:" \
     -F fileUrl=https://example.com/path/to/my_project.zip \
     -F name="My Project" \
     -F description="This is my project description" \
     https://api.plainlyvideos.com/api/v2/projects
```

--------------------------------

### Layer Management Script - Extended Properties Example

Source: https://help.plainlyvideos.com/docs/user-guide/projects/templates/template-creation/scripting/layer-management

This JSON example shows how to set multiple layer properties simultaneously using the layer management script. It includes duration, startTime, enabled state, audio enablement, font, and fontSize. This allows for comprehensive control over layer appearance and behavior in a single render call.

```json
{
	"projectId": "5bf8483b-a591-476a-afff-0db5fe1ea70f",
	"parameters": {
		"my_layer_mng": {
			"duration": 10,
			"startTime": 2,
			"enabled": true,
			"audioEnabled": false,
			"font": "Montserrat-ExtraBoldItalic",
			"fontSize": 32
		}
	}
}
```

--------------------------------

### Authentication API

Source: https://help.plainlyvideos.com/docs/developer-guide/authentication-and-setup

Describes the base endpoint and authentication mechanism for the Plainly API using HTTP Basic authentication with an API key.

```APIDOC
## GET /api/v2/renders

### Description
Fetches a list of recent renders from the Plainly API.

### Method
GET

### Endpoint
https://api.plainlyvideos.com/api/v2/renders

### Authentication
HTTP Basic authentication is used where the API key is sent as the username and the password is left blank.

### Request Example
```
curl -u "$PLAINLY_API_KEY:" \
     https://api.plainlyvideos.com/api/v2/renders
```

### Response
#### Success Response (200)
Returns a JSON array describing the renders, including their IDs and status.

#### Response Example
```
[
  {
    "id": "render123",
    "status": "completed"
  }
]
```
```

--------------------------------

### API Error Payload Example

Source: https://help.plainlyvideos.com/docs/troubleshooting/rendering-issues

An example of a typical API error response payload, including an error code, a descriptive message, and additional parameters for context.

```APIDOC
## GET /websites/help_plainlyvideos/error_example

### Description
Provides an example of an API error payload, illustrating the structure and common fields returned during an error.

### Method
GET

### Endpoint
/websites/help_plainlyvideos/error_example

### Parameters
#### Query Parameters
- **errorCode** (string) - Optional - Filters the error examples by a specific error code.

### Request Example
```json
{
  "errorCode": "WORKER_SCRIPT_COMPOSITION_NOT_FOUND"
}
```

### Response
#### Success Response (200)
- **code** (string) - The error code identifying the type of error.
- **message** (string) - A human-readable description of the error.
- **params** (object) - An object containing additional parameters specific to the error.
  - **log** (string) - Log details related to the error.
  - **cmdArgs** (array) - Command arguments associated with the error.

#### Response Example
```json
{
  "code": "WORKER_FFMPEG_ENCODING_ERROR",
  "message": "Ffmpeg encoding error.",
  "params": {
    "log": "FFmpeg error log here",
    "cmdArgs": [
      "FFmpeg command arguments here"
    ]
  }
}
```
```

--------------------------------

### Fetch list of recent renders using cURL

Source: https://help.plainlyvideos.com/docs/developer-guide/authentication-and-setup

Demonstrates a simple cURL command that authenticates with and retrieves a JSON array of recent renders. Replace the placeholder with your actual API key. The request uses HTTP Basic authentication with an empty password.

```Shell
curl -u "$PLAINLY_API_KEY:" \
    .plainlyvideos.com/api/v2/renders
```

--------------------------------

### Convert MOV to MP4 using FFmpeg

Source: https://help.plainlyvideos.com/docs/troubleshooting/analysis-issues

This command-line example demonstrates how to convert a MOV video file to an MP4 format using FFmpeg. It specifies the H.264 codec for video and AAC for audio, optimizing for web playback with the `faststart` flag. Ensure FFmpeg is installed and accessible in your system's PATH.

```bash
ffmpeg -i input.mov -c:v libx264 -c:a aac -movflags +faststart output.mp4
```

--------------------------------

### JSON Example: API Error Payload

Source: https://help.plainlyvideos.com/docs/troubleshooting/rendering-issues

This snippet demonstrates a sample JSON payload for an API error response, containing an error code, message, and parameters such as log details and FFmpeg command arguments. It serves as a reference for handling intermittent encoding errors in worker scripts. No external dependencies are required, as it is a static data example.

```json
{
  "code": "WORKER_FFMPEG_ENCODING_ERROR",
  "message": "Ffmpeg encoding error.",
  "params": {
    "log": "FFmpeg error log here",
    "cmdArgs": [
      "FFmpeg command arguments here"
    ]
  }
}
```

--------------------------------

### GET /api/v2/projects

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

Retrieves a list of all projects that the authenticated user has access to, providing an overview of available projects for management and rendering operations.

```APIDOC
## GET /api/v2/projects

### Description
Lists all projects accessible to the authenticated user, providing a comprehensive view of project inventory for management purposes.

### Method
GET

### Endpoint
https://api.plainlyvideos.com/api/v2/projects

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
{
  "headers": {
    "Authorization": "Basic [API_KEY]:"
  }
}

### Response
#### Success Response (200)
- **data** (array) - List of project objects with basic project information

#### Response Example
{
  "data": [
    {
      "id": "project-123",
      "name": "Marketing Video",
      "description": "Product promotion video",
      "status": "analyzed",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
```

--------------------------------

### Manual Template Creation (curl) - With Parameter

Source: https://help.plainlyvideos.com/docs/developer-guide/templates-api

Create a template manually, including a layer as a parameter.  Requires Plainly API key and project ID.  The example defines a media layer named 'Media Layer' with ID '2'.

```bash
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\tLayer",
			"layerType": "MEDIA",
			"mediaType": "image",
			"label": "Main image",
			"parametrization": {
				"expression": true,
				"value": "#logo"
			}
		}
		]
	}'
```

--------------------------------

### Parameter Reference Syntax for Dynamic Values

Source: https://help.plainlyvideos.com/docs/user-guide/projects/templates/template-management

Demonstrates the syntax for referencing template parameters within option values, allowing for dynamic configurations. Includes examples for optional default values and combining references with static text. Used for fields like file names and passthrough values.

```plaintext
{{parameterName:defaultValue}}
{{parameterName:}}
{{name}} - {{season:Winter}} Sale Project - 16x9
```

--------------------------------

### API cURL: Create Render with Project Files Upload

Source: https://help.plainlyvideos.com/docs/user-guide/rendering/creating-renders/render-options

An example using cURL to create a video render with the option to upload project files. The JSON payload includes `projectFiles.uploadEnabled: true` to enable this feature.

```shell
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "projectId": "[PROJECT_ID]",
        "options": {
          "projectFiles": {
            "uploadEnabled": true
          }
        }
      }' \
  https://api.plainlyvideos.com/api/v2/renders
```

--------------------------------

### Auto-generate Template (curl)

Source: https://help.plainlyvideos.com/docs/developer-guide/templates-api

Automatically generate a template based on the After Effects project structure. This example uses the 'all' type and targets all layers in the 'Main' composition. Requires Plainly API key and project ID.

```bash
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
	}'
```

--------------------------------

### Create Render with After Effects Output Module (cURL)

Source: https://help.plainlyvideos.com/docs/user-guide/rendering/creating-renders/output-formats

This example demonstrates how to create a render using a specific After Effects output module via a cURL command. It specifies the 'H_264_HIGH_BIT_RATE' output module for the render. Ensure you replace '[API_KEY]' and '[PROJECT_ID]' with your actual credentials.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "projectId": "[PROJECT_ID]",
        "outputFormat": {
          "outputModule": "H_264_HIGH_BIT_RATE"
        }
      }' \
  https://api.plainlyvideos.com/api/v2/renders
```

--------------------------------

### Create Draft Render (cURL)

Source: https://help.plainlyvideos.com/docs/user-guide/rendering/creating-renders/output-formats

Example of creating a draft render using cURL for a faster preview of the video. The draft option renders at half resolution and lower quality, making it ideal for quick checks before final rendering.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "projectId": "[PROJECT_ID]",
        "outputFormat": {
          "settingsTemplate": "DRAFT"
        }
      }' \
  https://api.plainlyvideos.com/api/v2/renders
```

--------------------------------

### API cURL Example - Auto-generate Templates (Prefix Type)

Source: https://help.plainlyvideos.com/docs/user-guide/projects/templates/template-creation

This cURL command demonstrates how to use the Plainly API to auto-generate video templates based on a specified prefix. It requires an API key and project ID, and accepts a JSON payload to configure the generation process, including options for layer parametrization and composition targeting.

```shell
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "type": "prefix",
        "allLayers": false,
        "applyExclusionsToCompositions": true,
        "excludeAdjustmentLayers": false,
        "excludeDisabledLayers": false,
        "excludeGuideLayers": false,
        "excludeShyLayers": false,
        "greedy": false,
        "targetCompositionName": "string",
        "prefixes": "[\"plainly\"]",
        "stripPrefix": false
      }' \
  https://api.plainlyvideos.com/api/v2/projects/[PROJECT_ID]/templates/auto-generate
```

--------------------------------

### GET /api/v2/projects/{projectId}

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

Retrieve detailed information about a specific project including its current analysis state and other properties.

```APIDOC
## GET /api/v2/projects/{projectId}

### Description
Get detailed information about a specific project including its analysis state, templates, and other metadata.

### Method
GET

### Endpoint
/api/v2/projects/{projectId}

### Parameters
#### Path Parameters
- **projectId** (string) - Required - Unique identifier of the project

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the project
- **name** (string) - Name of the project
- **description** (string) - Description of the project
- **size** (number) - Size of the uploaded project in bytes
- **analysis** (object) - Analysis status details
- **templates** (array) - Available templates for the project

#### Response Example
```
{
  "name": "My Project",
  "id": "00000000-acf3-4d3e-bb48-07036d023220",
  "size": 32235740,
  "attributes": {
    "tags": []
  },
  "lastModified": "2025-07-30T11:07:02.309Z",
  "description": "This is my project description",
  "sharingLinks": null,
  "createdBy": null,
  "createdDate": "2025-07-30T11:07:02.309Z",
  "revisionHistory": null,
  "sharing": null,
  "aeVersion": "AE2025",
  "defaultTemplateId": null,
  "templates": [],
  "uploaded": true,
  "analyzed": false,
  "strictFontChecks": null,
  "analysis": {
    "pending": false,
    "done": false,
    "failed": false,
    "error": null,
    "upgradeError": null
  }
}
```
```

--------------------------------

### API cURL Example - Create Render with Basic Webhook

Source: https://help.plainlyvideos.com/docs/user-guide/rendering/video-delivery

This cURL command demonstrates how to create a video render using the PlainlyVideos API. It includes a basic webhook configuration with a specified URL, passthrough data, and options for handling failures and invalid renders. The request uses a POST method with JSON payload and requires API key authentication.

```curl
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{ \
        "projectId": "[PROJECT_ID]", \
        "webhook": { \
          "url": "https://example.com/webhook", \
          "passthrough": "customer_id=12345", \
          "onFailure": true, \
          "onInvalid": false \
        } \
      }' \
  https://api.plainlyvideos.com/api/v2/renders
```

--------------------------------

### POST /api/renders

Source: https://help.plainlyvideos.com/docs/user-guide/projects/templates/template-creation/scripting/image-sequence

Creates a new render job with an image sequence parameter. Requires prior setup of image sequence script on a video or image layer. The parameter name defined in the script must match the key used in the API request parameters object to swap the layer with the provided image sequence.

```APIDOC
## POST /api/renders

### Description
Creates a new render job with an image sequence parameter. This endpoint allows you to dynamically replace a video or image layer with a sequence of images by providing an array of image URLs. The image sequence functionality requires prior setup: add the image sequence script to your target layer and define a parameter name in the script. This parameter name must then be included in the `parameters` object of your API request.

### Method
POST

### Endpoint
/api/renders

### Parameters
#### Request Body
- **projectId** (string) - Required - The unique identifier of the project to render
- **parameters** (object) - Required - Object containing render parameters
  - **image_sequence** (array of strings) - Required - Array of image URLs to be used as a sequence. The key must match the parameter name defined in your layer script.

### Request Example
{
  "projectId": "5bf8483b-a591-476a-afff-0db5fe1ea70f",
  "parameters": {
    "image_sequence": [
      "https://cdn.filestackcontent.com/0ITCVdATSZyyUpP4JRvu",
      "https://cdn.filestackcontent.com/4eOvgf8hR3OcaPTW5wZb",
      "https://cdn.filestackcontent.com/G9JSG5YQhuswnPuCaq8S",
      "https://cdn.filestackcontent.com/Wp7VUtnpTpW82jg0Z2h0",
      "https://cdn.filestackcontent.com/M05K3YEpSHCoeOx2AFTW"
    ]
  }
}

### Response
#### Success Response (200)
- **renderId** (string) - The unique identifier for the created render job
- **status** (string) - Status of the render job (e.g., "queued", "processing")
- **message** (string) - Success message

#### Response Example
{
  "renderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "message": "Render job created successfully"
}
```

--------------------------------

### Get flattened project metadata JSON

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

Sample JSON response showing metadata for compositions and media layers in a video editing project. Contains details about composition hierarchy, layer properties, timing, dimensions, and text styling. No external dependencies required.

```json
[
	{
		"compositions": [],
		"type": "COMPOSITION",
		"internalId": "16215",
		"name": "Single Product Promo",
		"value": null,
		"id": 16215,
		"duration": 6.03333333333333,
		"workAreaStart": 0.0,
		"width": 720.0,
		"height": 720.0,
		"layerName": null
	},
	{
		"compositions": [
			{
				"id": 16215,
				"internalId": "16215",
				"name": "Single Product Promo",
				"layerName": null,
				"path": "Single Product Promo",
				"inCompositionProps": {
					"startTime": 1.36,
					"inPoint": 1.36,
					"outPoint": 6.04,
					"guideLayer": false,
					"enabled": true,
					"adjustmentLayer": false,
					"shy": false
				}
			}
		],
		"type": "COMPOSITION",
		"internalId": "25984",
		"name": "discount comp",
		"value": null,
		"id": 25984,
		"duration": 4.68,
		"workAreaStart": 0.0,
		"width": 1080.0,
		"height": 194.0,
		"layerName": "discount comp"
	},
	{
		"compositions": [
			{
				"id": 25984,
				"internalId": "25984",
				"name": "discount comp",
				"layerName": "discount comp",
				"path": "Single Product Promo->discount comp",
				"inCompositionProps": {
					"startTime": 0.0,
					"inPoint": 0.0,
					"outPoint": 60.0,
					"guideLayer": false,
					"enabled": false,
					"adjustmentLayer": false,
					"shy": true
				}
			}
		],
		"type": "MEDIA",
		"internalId": "26045",
		"name": "boundingBox",
		"value": "#848484",
		"width": 250.0,
		"height": 500.0,
		"mediaType": "SOLID",
		"effects": []
	},
	{
		"compositions": [
			{
				"id": 25984,
				"internalId": "25984",
				"name": "discount comp",
				"layerName": "discount comp",
				"path": "Single Product Promo->discount comp",
				"inCompositionProps": {
					"startTime": -0.72,
					"inPoint": 0.0,
					"outPoint": 4.68,
					"guideLayer": false,
					"enabled": true,
					"adjustmentLayer": false,
					"shy": false
				}
			}
		],
		"type": "TEXT",
		"internalId": "26001",
		"name": "EDIT-discount",
		"value": "30% OFF",
		"font": "Poppins-Black",
		"fontLocation": "C:\\Program Files\\Common Files\\Adobe\\Fonts\\Poppins-Black.ttf",
		"fontStyle": "Black",
		"fontFamily": "Poppins",
		"fontSize": 266.0,
		"isParagraph": false,
		"allCaps": true,
		"leading": 25.0997009277344,
		"tracking": 0.0
	},
	{
		"compositions": [
			{
				"id": 16215,
				"internalId": "16215",
				"name": "Single Product Promo",
				"layerName": null,
				"path": "Single Product Promo",
				"inCompositionProps": {
					"startTime": 0.72,
					"inPoint": 0.72,
					"outPoint": 6.04,
					"guideLayer": false,
					"enabled": true,
					"adjustmentLayer": false,
					"shy": false
				}
			}
		],
		"type": "COMPOSITION",
		"internalId": "26013",
		"name": "price comp",
		"value": null,
		"id": 26013,
		"duration": 5.32,
		"workAreaStart": 0.0,
		"width": 1080.0,
		"height": 228.0,
		"layerName": "price comp"
	},
	{
		"compositions": [
			{
				"id": 26013,
				"internalId": "26013",
				"name": "price comp",
				"layerName": "price comp",
				"path": "Single Product Promo->price comp",
				"inCompositionProps": {
					"startTime": 0.0,
					"inPoint": 0.0,
					"outPoint": 60.0,
					"guideLayer": false,
					"enabled": false,
					"adjustmentLayer": false,
					"shy": true
				}
			}
		],
		"type": "MEDIA",
		"internalId": "26043",
		"name": "boundingBox",
		"value": "#848484",
		"width": 250.0,
		"height": 500.0,
		"mediaType": "SOLID",
		"effects": []
	},
	{
		"compositions": [
			{
				"id": 26013,
				"internalId": "26013",
				"name": "price comp",
				"layerName": "price comp",
				"path": "Single Product Promo->price comp",
				"inCompositionProps": {
					"startTime": -0.72,
					"inPoint": 0.0,
					"outPoint": 5.32,
					"guideLayer": false,
					"enabled": true,
					"adjustmentLayer": false,
					"shy": false
				}
			}
		],
		"type": "TEXT",
		"internalId": "26028",
		"name": "EDIT-price",
		"value": "$199,99",
		"font": "Poppins-Black",
		"fontLocation": "C:\\Program Files\\Common Files\\Adobe\\Fonts\\Poppins-Black.ttf",
		"fontStyle": "Black",
		"fontFamily": "Poppins",
		"fontSize": 266.0,
		"isParagraph": false,
		"allCaps": false,
		"leading": 31.9737205505371,
		"tracking": 0.0
	},
	{
		"compositions": [
			{
				"id": 16215,
				"internalId": "16215",
				"name": "Single Product Promo",
				"layerName": null,
				"path": "Single Product Promo",
				"inCompositionProps": {
					"startTime": 0.0,
					"inPoint": 0.0,
					"outPoint": 6.04,
					"guideLayer": false,
					"enabled": true,
					"adjustmentLayer": false,
					"shy": false
				}
			}
		],
		"type": "COMPOSITION",
		"internalId": "25942",
		"name": "product pic comp",
		"value": null,
		"id": 25942,
		"duration": 6.04,
		"workAreaStart": 0.0,
		"width": 500.0,
		"height": 500.0,
		"layerName": "product pic comp"
	},
	{
		"compositions": [
			{
				"id": 25942,
				"internalId": "25942",
				"name": "product pic comp",
				"layerName": "product pic comp",
				"path": "Single Product Promo->product pic comp",
				"inCompositionProps": {
					"startTime": 0.0,
					"inPoint": 0.0,
					"outPoint": 60.0,
					"guideLayer": false,
					"enabled": false,
					"adjustmentLayer": false,
					"shy": true
				}
			}
		],
		"type": "MEDIA",
		"internalId": "26041",
		"name": "boundingBox",
		"value": "#848484",
		"width": 250.0,
		"height": 500.0,
		"mediaType": "SOLID",
		"effects": []
	}
]
```

--------------------------------

### Dynamic Passthrough using Render Parameter

Source: https://help.plainlyvideos.com/docs/user-guide/integrations/video-distribution

This example shows how to set a dynamic passthrough value by referencing a render parameter. The value of the specified render parameter (e.g., `customerName`) will be inserted into the passthrough string during the render process.

```text
customer:{{customerName}}
```

--------------------------------

### Create Render with Custom Post Encoding (cURL)

Source: https://help.plainlyvideos.com/docs/user-guide/rendering/creating-renders/output-formats

Example of creating a video render with custom post-encoding settings using cURL. This allows specifying an encoding format (e.g., MP4) and custom FFmpeg parameters for fine-grained control over the output.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "projectId": "[PROJECT_ID]",
        "outputFormat": {
          "postEncoding": {
            "type": "custom",
            "encodingFormat": "MP4",
            "encodingParamsLine": "-c:a aac -b:a 192k"
          }
        }
      }' \
  https://api.plainlyvideos.com/api/v2/renders
```

--------------------------------

### GET /api/v2/projects/{projectId}/meta

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

Retrieves the complete metadata structure of a project including compositions, media assets, effects, and their hierarchical relationships. Returns a 404 error if the project hasn't been analyzed yet.

```APIDOC
## GET /api/v2/projects/{projectId}/meta

### Description
Retrieves the complete metadata structure of a project including all compositions, media assets, effects, and their hierarchical relationships. Used for programmatic analysis of project content.

### Method
GET

### Endpoint
https://api.plainlyvideos.com/api/v2/projects/{projectId}/meta

### Parameters
#### Path Parameters
- **projectId** (string) - Required - Unique project identifier

#### Query Parameters
None

#### Request Body
None

### Request Example
{
  "headers": {
    "Authorization": "Basic [API_KEY]:"
  }
}

### Response
#### Success Response (200)
- **data** (array) - Array of project metadata objects containing:
  - **compositions** (array) - List of compositions in the project
  - **type** (string) - Asset type (MEDIA, COMPOSITION, etc.)
  - **internalId** (string) - Unique internal identifier
  - **name** (string) - Asset name
  - **value** (string) - Asset value/URL
  - **width/height** (number) - Asset dimensions
  - **mediaType** (string) - Type of media (IMAGE, VIDEO, SOLID, etc.)
  - **effects** (array) - List of effects applied to the asset
  - **preview** (object) - Preview link information

#### Response Example
[
  {
    "compositions": [
      {
        "id": 16215,
        "internalId": "16215",
        "name": "Single Product Promo",
        "path": "Single Product Promo",
        "inCompositionProps": {
          "startTime": 0.0,
          "inPoint": 0.0,
          "outPoint": 6.04,
          "enabled": true
        }
      }
    ],
    "type": "MEDIA",
    "internalId": "25954",
    "name": "EDIT-example 2 product pic",
    "value": "(Footage)/Assets/generic%20keyboard.jpg",
    "width": 500.0,
    "height": 500.0,
    "mediaType": "IMAGE",
    "effects": [
      {
        "type": "EFFECT_CHECKBOX_CONTROL",
        "name": "STC - Scale to Fit (Maintain Ratio)",
        "propertyName": "Effects.STC - Scale to Fit (Maintain Ratio).Checkbox",
        "value": 1
      }
    ],
    "preview": {
      "link": "https://example.com/preview/25954",
      "expiresAt": "2025-08-12T14:01:59.117749219Z"
    }
  }
]

#### Error Response (404)
Project analysis not yet complete or project ID does not exist.
```

--------------------------------

### Set Default Render Options using cURL

Source: https://help.plainlyvideos.com/docs/user-guide/projects/templates/template-management

Example cURL command to set default rendering options for a template, including captions, project files, and watermarks. It demonstrates how to specify output format settings like attachment and encoding. This requires API Key, Project ID, and Template ID.

```curl
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{
        "options": {
          "captions": {
            "captionsPosition": "TOP",
            "captionsStyle": "BASIC_WITH_STROKE_AND_SHADOW",
            "srtFileUrl": "https://my.cnd.net/srt.srt"
          },
          "projectFiles": {
            "uploadEnabled": true
          },
          "watermark": {
            "url": "https://example.com/watermark.png"
          }
        },
        "outputFormat": {
          "attachment": false,
          "attachmentFileName": "my_cool_video",
          "outputModule": "H_264",
          "postEncoding": {
            "type": "none"
          },
          "settingsTemplate": "BEST_SETTINGS"
        }
      }' \
  https://api.plainlyvideos.com/api/v2/projects/[PROJECT_ID]/templates/[TEMPLATE_ID]/options
```

--------------------------------

### API Error Payload: WORKER_FONT_INSTALL_FAILED (Font Installation)

Source: https://help.plainlyvideos.com/docs/troubleshooting/rendering-issues

Example of an API error payload indicating a failure to install fonts during rendering. This usually arises from unsupported or corrupted external fonts provided via Layer management scripts.

```json
{
  "code": "WORKER_FONT_INSTALL_FAILED",
  "message": "Failed to install fonts: https://myserver/fonts/ArialMT.ttf",
  "params": {
    "fonts": [
      "https://myserver/fonts/ArialMT.ttf"
    ]
  }
}
```

--------------------------------

### POST /api/v2/projects (Create from URL)

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

Create a new project by providing a URL to a ZIP file. Plainly will download the file server-side and process it. The project will then undergo analysis.

```APIDOC
## POST /api/v2/projects

### Description
Create a project by providing a URL to a ZIP file that Plainly will download. The project will be analyzed and transition through various states based on the analysis outcome.

### Method
POST

### Endpoint
/api/v2/projects

### Parameters
#### Request Body
- **fileUrl** (string) - Required - Publicly accessible URL to the ZIP file
- **name** (string) - Optional - Name of the project
- **description** (string) - Optional - Description of the project

### Request Example
```
curl -u "$PLAINLY_API_KEY:"
     -F fileUrl=https://example.com/path/to/my_project.zip
     -F name="My Project"
     -F description="This is my project description"
     https://api.plainlyvideos.com/api/v2/projects
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the project
- **name** (string) - Name of the project
- **description** (string) - Description of the project
- **size** (number) - Size of the uploaded project in bytes
- **analysis** (object) - Analysis status details

#### Response Example
```
{
  "name": "My Project",
  "id": "00000000-acf3-4d3e-bb48-07036d023220",
  "size": 32235740,
  "attributes": {
    "tags": []
  },
  "lastModified": "2025-07-30T11:07:02.309Z",
  "description": "This is my project description",
  "sharingLinks": null,
  "createdBy": null,
  "createdDate": "2025-07-30T11:07:02.309Z",
  "revisionHistory": null,
  "sharing": null,
  "aeVersion": "AE2025",
  "defaultTemplateId": null,
  "templates": [],
  "uploaded": true,
  "analyzed": false,
  "strictFontChecks": null,
  "analysis": {
    "pending": false,
    "done": false,
    "failed": false,
    "error": null,
    "upgradeError": null
  }
}
```
```

--------------------------------

### After Effects Error API Payload Example

Source: https://help.plainlyvideos.com/docs/troubleshooting/intermittent-issues

Example API error payload for a WORKER_AFTER_EFFECTS_ERROR. This indicates an issue during automated rendering in After Effects, often due to project-specific problems. The 'log' parameter provides details from the After Effects aerender process.

```json
{
  "code" : "WORKER_AFTER_EFFECTS_ERROR",
  "message" : "Could not render the video.",
  "params" : {
    "log" : "aerender version 25.1x68\r\nPROGRESS: Launching After Effects..."
  }
}
```

--------------------------------

### Infrastructure Failure API Payload Example

Source: https://help.plainlyvideos.com/docs/troubleshooting/intermittent-issues

Example API error payload for an INFRASTRUCTURE_FAILURE. This indicates a temporary problem with the platform's job management system, preventing job submission. Retrying after a short wait is usually sufficient for resolution.

```json
{
  "code" : "INFRASTRUCTURE_FAILURE",
  "message" : "Failed to submit render job to worker queue."
}
```

--------------------------------

### Fatal Error API Payload Example

Source: https://help.plainlyvideos.com/docs/troubleshooting/intermittent-issues

Example API error payload for a WORKER_FATAL_ERROR. This signifies an internal platform issue rather than a project error, indicating a bug or unhandled condition within the PlainlyVideos system. Contacting support is recommended.

```json
{
  "code" : "WORKER_FATAL_ERROR",
  "message" : "Unexpected error occurred, please contact support."
}
```

--------------------------------

### POST /api/v2/projects

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

Upload an After Effects project as a ZIP file to create a new project. The project will be analyzed and transition through various states based on the analysis outcome.

```APIDOC
## POST /api/v2/projects

### Description
Upload a ZIP package containing After Effects project files to create a new project. The project analysis will begin automatically after upload.

### Method
POST

### Endpoint
/api/v2/projects

### Parameters
#### Request Body
- **file** (file) - Required - ZIP file containing the project and assets
- **name** (string) - Optional - Name of the project
- **description** (string) - Optional - Description of the project

### Request Example
```
curl -u "$PLAINLY_API_KEY:"
     -F file=@my_project.zip
	 -F name="My Project"
	 -F description="This is my project description"
     https://api.plainlyvideos.com/api/v2/projects
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the project
- **name** (string) - Name of the project
- **description** (string) - Description of the project
- **size** (number) - Size of the uploaded project in bytes
- **analysis** (object) - Analysis status details

#### Response Example
```
{
  "name": "My Project",
  "id": "00000000-acf3-4d3e-bb48-07036d023220",
  "size": 32235740,
  "attributes": {
    "tags": []
  },
  "lastModified": "2025-07-30T11:07:02.309Z",
  "description": "This is my project description",
  "sharingLinks": null,
  "createdBy": null,
  "createdDate": "2025-07-30T11:07:02.309Z",
  "revisionHistory": null,
  "sharing": null,
  "aeVersion": "AE2025",
  "defaultTemplateId": null,
  "templates": [],
  "uploaded": true,
  "analyzed": false,
  "strictFontChecks": null,
  "analysis": {
    "pending": false,
    "done": false,
    "failed": false,
    "error": null,
    "upgradeError": null
  }
}
```
```

--------------------------------

### Timeout Error API Payload Example

Source: https://help.plainlyvideos.com/docs/troubleshooting/intermittent-issues

Example API error payload for a WORKER_TIMEOUT error. This occurs when After Effects execution exceeds the time limit, typically due to project complexity, heavy assets, or infrastructure slowdowns. Retrying the render is often the solution.

```json
{
  "code" : "WORKER_TIMEOUT",
  "message" : "Rendering exceeded time limit."
}
```

--------------------------------

### POST /api/v2/projects

Source: https://help.plainlyvideos.com/docs/developer-guide/projects-api

Creates a new project by uploading a ZIP file containing the After Effects project. The project will be automatically analyzed and made available for rendering.

```APIDOC
## POST /api/v2/projects

### Description
Creates a new project by uploading a ZIP file containing the After Effects project. The project is automatically analyzed and prepared for rendering.

### Method
POST

### Endpoint
https://api.plainlyvideos.com/api/v2/projects

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (file) - Required - ZIP file containing the After Effects project
- **name** (string) - Required - Project name/identifier
- **description** (string) - Optional - Project description

### Request Example
{
  "multipart/form-data": {
    "file": "[ZIP file contents]",
    "name": "My Project",
    "description": "This is my project description"
  }
}

### Response
#### Success Response (200)
- **data** (object) - Project creation response with project details

#### Response Example
{
  "data": "Project created successfully"
}
```

--------------------------------

### Render with Skip All Integrations (API cURL)

Source: https://help.plainlyvideos.com/docs/user-guide/integrations/video-distribution

This cURL command demonstrates how to make a POST request to the Plainly Videos API to create a render while skipping all video distribution integrations. It requires API key, project ID, and template ID as parameters. The `skipAll: true` option within the `integrations` object controls this behavior.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -u "[API_KEY]:" \
  -d '{ \
        "projectId": "[PROJECT_ID]", \
        "templateId": "[TEMPLATE_ID]", \
        "options": { \
          "integrations": { \
            "skipAll": true \
          } \
        }' \
  https://api.plainlyvideos.com/api/v2/renders
```

--------------------------------

### Plainly MCP Server Configuration (JSON)

Source: https://help.plainlyvideos.com/docs/mcp-server

This JSON configuration is used to set up the Plainly MCP server. It specifies the command to run the server and environment variables, including the essential Plainly API key.

```json
{
	"plainly": {
		"command": "npx",
		"args": ["-y", "@plainly-videos/mcp-server@latest"],
		"env": {
			"PLAINLY_API_KEY": "<PLAINLY_API_KEY>"
		}
	}
}
```

```json
{
	"mcpServers": {
		"plainly": {
			"command": "npx",
			"args": ["-y", "@plainly-videos/mcp-server@latest"],
			"env": {
				"PLAINLY_API_KEY": "<PLAINLY_API_KEY>"
			}
		}
	}
}
```

```json
{
	"servers": {
		"plainly": {
			"command": "npx",
			"args": ["-y", "@plainly-videos/mcp-server@latest"],
			"env": {
				"PLAINLY_API_KEY": "<PLAINLY_API_KEY>"
			}
		}
	}
}
```
Tokens:
Raw