JSON2Video API is the easiest way to create, edit and customise videos programmatically. Its dead simple approach, close 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 text animations and voice generation (TTS) converts JSON2Video in the best solution in its category.

How to create a movie?

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

Check JSON2Video API specification to learn about how to create this JSON document.

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

curl --location --request POST 'https://api.json2video.com/v1/movies' \
--header 'x-api-key: [[YOUR_APIKEY]]' \
--header 'Content-Type: application/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.

Once the job has been started on the server, you can check its status to find out what stage it is in, if it has been completed or if an error has occurred:

curl --location --request GET 'https://api.json2video.com/v1/movies' \
--header 'x-api-key: [[YOUR_APIKEY]]'

The movie document

Movie JSON documents have the following structure:

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

The project_id property is a string that names your project. Possible examples for project_id: “myproject”, “my_project”, “myProject”, “output1”, etc. The resulting video file will be named using the project_id, for example “myproject.mp4”.

The scenes property is an array of other JSON objects defining a scene. 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 (and in parallel), and finally all of them are chained together to compose the final movie. When concatenating them, you can apply a transition between scenes to smooth the change between them.

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

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

IMPORTANT: Probably the most important property is duration, which defines the duration of the scene. If the JSON does not specify a 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 specifications.

All elements share at least the following properties:

• start: sets the starting point (in seconds) of the element, relative to the scene or to the movie
• duration: sets the duration (in seconds) of the element
• extra-time: adds additional time (in seconds) after duration ends

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 were not set, the scene would last 17 seconds.

IMPORTANT: 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

These elements that are visual (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.

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 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
}

IMPORTANT: 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.

Continue the tutorial

Continue reading the JSON2Video tutorial here:
https://json2video.com/docs/tutorial/