JSON2Video API is the easiest way to create, edit and customise videos programmatically. Its dead simple approach, similar to the web development mindset, makes it the ultimate solution for developers that want to create or customise videos in an automated way.

Additionally, the simple integration of real HTML5+CSS elements, the already built-in templates, animations and voice generation (TTS) converts JSON2Video in the best video editing API solution.

Authentication

All calls to the API require authentication.

You must pass your API key in the x-api-key header of your request.

How to create a movie?

The resulting video of a JSON2Video API call is called movie. A movie is created from a JSON document that specifies the properties of the resulting video as well as the content of the video.

Check JSON2Video API specification to learn about all properties of this JSON document.

To create a movie, you just call the endpoint /v2/movies with a POST request passing the JSON as payload: 

curl --location --request POST 'https://api.json2video.com/v2/movies' \
--header 'x-api-key: [[YOUR_APIKEY]]' \
--header 'Content-Type: application/json' \
--data-raw '[[YOUR_JSON]]'

The request returns immediately, but not before starting a server-side job that will create the movie. The job can take several minutes, depending on the complexity of the JSON script. The endpoint returns a project ID for that job. 

{
    "success": true,
    "project": "[[YOUR_PROJECT_ID]]",
    "timestamp": "2022-08-01T10:49:52.924Z"
}

Once the job started remotely, you can check the status, if it finished or if an error occurred: 

curl --location --request GET 'https://api.json2video.com/v2/movies?project=[[YOUR_PROJECT_ID]]' \
--header 'x-api-key: [[YOUR_APIKEY]]'

You can also get notified when the movie is ready via a webhook, or automate the publication to YouTube, to a FTP or SFTP server, or send an email. Check the Exports documentation for more details.

The movie document

Movie JSON documents have the following structure: 

{
    "scenes": [],
    "elements": []
}

The scenes property is an array of scene-type JSON objects defining the different scenes in the movie. Find more information below.

The elements property is an array of element JSON objects. Find more information below.

Using scenes

A movie can be structured in different scenes. The advantage of using scenes is that each one is rendered independently (in parallel!), and finally all of them are chained together to compose the final movie. You can apply a transition between scenes to smooth the change between them. 

{
    "scenes": [
        {
            "comment": "This is the scene #1",
            "duration": 10,
            "elements": []
        }
    ],
    "elements": []
}

Each scene is composed of elements (see below) and may have a few properties.

Probably the most important property is duration, which defines the duration of the scene. If the JSON does not provide an explicit duration, the scene will last as long as it needs to contain all its elements. If a duration is specified, the scene will be trimmed or lengthened to meet the duration.

Adding elements to a scene or movie

Both movies and scenes can contain elements. Elements are the basic unit of content in a movie or a scene, and they can be images, texts, audios, videos, etc.

Each type of element (image, audio, text, etc) has its own properties. You can learn about element types and how to use them later in this tutorial or the API specification.

All elements share at least the following properties:

Example of element: 

{
    "type": "[[ELEMENT_TYPE]]",
    "start": 5,
    "duration": 10,
    "extra-time": 2
}

In this case, the element will appear after 5 seconds and will last 10 seconds. The total time of the element will be 17 seconds (5 + 10 + 2 = 17). If this element were the only element in a scene and the duration of that scene was not set, the scene would last 17 seconds.

Like in the scenes, if duration is not set, the duration is calculated based on the length of the underlying asset (the video file, audio file, etc). If the duration is explicitely set, the element will trim the length of the underlying asset.

Position elements by coordinates

Visual elements (images, texts, videos) can be positioned on the scene or movie based on coordinates.

The coordinates system work like in a HTML web page: The 0,0 is on the top-left of the video canvas.

The x, y, width and height properties are simply measured in pixels.

Overlaying elements

The elements in the elements array of a scene or a movie are stacked like HTML elements: The first element of the array is placed below the second element, the second below the third and so on.

The last element of the array is therefore placed above all the others. If the elements overlap in the coordinate space, the upper elements will cover the lower elements. This may be counter-intuitive for Photoshop or After Effects users, but it follows the logic of HTML and CSS.

Caching and render optimisation

JSON2Video is designed to optimize video rendering as much as possible and reduce waiting time. To do this, it uses a caching system to avoid repeatedly downloading the same files over and over again, or re-rendering templates or scenes that have not changed.

This system is smart enough to rebuild a scene or movie when one of the elements has changed. However, you can force the refresh of an element, a scene or the whole movie with the cache property.

Example forcing an element to be rendered from scratch: 

{
    "type": "[[ELEMENT_TYPE]]",
    "cache": false
}

The cache property is not inherited by child objects. This means that setting a cache:false to a scene only forces the scene to be rendered again, but the elements are not flushed.

How to check if your movie is rendered

The POST request starts a server-side job that creates and renders your movie, but it returns immediately.

To check if your movie is completed and ready, you must send a GET request passing the project id returned by the POST request. 

/v2/movies?project=[[YOUR_PROJECT_ID]]

If everything went fine, the response should look like this: 

{
    "success": true,
    "movie": {
        "success": true,
        "status": "done",
        "message": "",
        "url": "https://assets.json2video.com/clients/bm1pc474m4/renders/2022-08-14-99359.mp4",
        "created_at": "2022-08-01T10:49:52.924Z",
        "ended_at": "2022-08-01T10:50:58.142Z",
        "duration": 20.32,
        "size": 26551424,
        "width": 1920,
        "height": 1080
    },
    "remaining_quota": {
        "movies": 0,
        "drafts": 11
    }
}

The url field provides you a link to download your movie.