Skip to main content

Create videos with API

This documentation shows an example of creating a single video using Shakr API.

Requirements​

Fetch Template mapping specification​

To change design elements in the template you've chosen, you can refer to template's mapping specification. Mapping specification includes information including design elements that can be edited, and you can construct a mapping object which you can use to make an API call to create RenderSession.

For this example, we will use a template called Skin Company, a cheerful, simple-to-create template from Shakr Template Library.

curl 'https://api.shakr.com/v2/template_style_versions/TEMPLATE_STYLE_VERSION_ID/specs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SERVER_ACCESS_TOKEN'
{
  "style_version": {
    ... // Mapping specification
  }
}

Sample mapping specification​

Here is a sample mapping specification of Skin Company template.

{
  "style_version": {
    "id": "xQGAFq",
    "editables": {
      "c_01": {
        "input_type": "color",
        "example_text": "EEADA7",
        "stillcut": "stillcut_01",
        "fonts": [
          "Montserrat-Regular"
        ]
      },

      ...

      "t_01": {
        "input_type": "text",
        "example_text": "Skin care",
        "stillcut": "stillcut_01",
        "fonts": [
          "AbrilFatface-Regular"
        ]
      },

      ...

      "(Footage)/USER/logo_01.png": {
        "input_type": "image",
        "width": 550,
        "height": 180,
        "stillcut": "stillcut_01"
      },

      ...

    },
    "fonts": [
      "Montserrat-Regular",
      "AbrilFatface-Regular",
      "Montserrat-Medium"
    ]
  }
}

From above, the most important part would be the editables object. As the name suggests, it contains elements that can be edited, such as images, videos, and text. You can check the type of editables by referring to input_type.

See also​

Build your mapping data​

After getting mapping specification, you can now build your mapping data and fill in text or media assets. Since the sample template contains text and image editables, we'll explore how to build editable data for those two types.

Text editables​

Text editables are the simplest form of editables that display text in the video. If you want to assign My video text text value to t_01 text editable, you can add it to your mapping data like below.

{
  "t_01": {
    "source": { "text": "My video text" }
  }
}

Image editables​

Image editables display images within a video and can be utilized in various ways such as photos of a product or brand logos. You need to assign URL of the image file you want to use, and how you would like to handle the image. (i.e. Cropping) For more information, please refer to Image editable documentation.

If you want to place https://via.placeholder.com/1280x720.jpg image onto (Footage)/USER/logo_01.png editable and fill in the display area without a gap, you can add it to your mapping data like below.

{
  "(Footage)/USER/logo_01.png": {
    "source": {
      "remote_url": "https://via.placeholder.com/1280x720.jpg"
    },
    "transform": {
      "crop_strategy": "cover"
    }
  }
}

Go through all editables on mapping specification, and your mapping data is complete.

See also​

Create a RenderSession​

Since now we have all the info needed to create a video, we can now create a RenderSession. mapping object contains template_style_version_id, which we acquired beforehand, and resources object, which contains resources information within the mapping. Let's look at a sample request below.

curl 'https://api.shakr.com/v2/render_sessions' \
  -X POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SERVER_ACCESS_TOKEN'
  --data-raw '{
    "title": "My New Video (Using Skin Company template)",
    "render": "preview",
    "mapping": {
      "template_style_version_id": "xQGAFq",
      "resources": {
        "t_01": { "source": { "text": "Skin beauty" } },
        "t_02": { "source": { "text": "delivered" } },
        "t_03": { "source": { "text": "just for you" } },
        "t_04": { "source": { "text": "only at " } },
        "t_05": { "source": { "text": "EXCLUSIVE TRIAL OFFER" } },
        "(Footage)/USER/logo_01.png": {
          "source": { "remote_url": "https://via.placeholder.com/550x180.png" },
          "transform": { "crop_strategy": "cover" }
        },
        "(Footage)/USER/user_02.jpg": {
          "source": { "remote_url": "https://via.placeholder.com/1680x1050.jpg" },
          "transform": { "crop_strategy": "cover" }
        }
      }
    }
  }'
{
  "render_session": {
    "id": "RENDER_SESSION_ID",
    "title": "My New Video (Using Skin Company template)",
    "status": "preview_rendering",
    "render_progress": 0,
    "thumbnails": [],
    "video_url": null,
    "errors": [],
    "created_at": "2030-01-01T07:20:22.527Z",
    "updated_at": "2030-01-01T07:20:22.619Z",
    "mapping": {
      "id": "MAPPING_ID",
      "template_style_version_id": "xQGAFq",
      "resources": {
        "t_01": { "source": { "text": "Skin beauty" } },
        "t_02": { "source": { "text": "delivered" } },
        "t_03": { "source": { "text": "just for you" } },
        "t_04": { "source": { "text": "only at " } },
        "t_05": { "source": { "text": "EXCLUSIVE TRIAL OFFER" } },
        "(Footage)/USER/logo_01.png": {
          "source": { "remote_url": "https://via.placeholder.com/550x180.png" },
          "transform": { "crop_strategy": "cover" }
        },
        "(Footage)/USER/user_02.jpg": {
          "source": { "remote_url": "https://via.placeholder.com/1680x1050.jpg" },
          "transform": { "crop_strategy": "cover" }
        }
      }
    },
    "audio_tracks": {},
    "font_changes": {},
    "source_uploads": [],
    "fonts": []
  }
}

When the request is successful, you can see that render_session object is successfully returned.

See also​

Check rendered video​

When status property in RenderSession object changes to preview_rendered, it means that the video is ready. You can fetch the completed video's URL by looking into video_url property.

curl 'https://api.shakr.com/v2/render_sessions/RENDER_SESSION_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SERVER_ACCESS_TOKEN'
{
  "render_session": {
    "id": "<RENDER_SESSION_ID>",
    "title": "My New Video",
    "status": "preview_rendered",
    "render_progress": 100,
    "thumbnails": ["IMAGE_URL"],
    "video_url": "VIDEO_URL",

    ...

  }
}

Congratulations, now you have made a video using Shakr API! 🎉

See also​



More features of Shakr API​