11. Templates#

Variables let one JSON serve many properties. Templates let your application avoid sending that JSON at all — store the movie once in your Dashboard, then trigger a render with { "template": "<id>", "variables": { ... } }. This chapter walks through saving the chapter-10 movie as a template and calling it from the API.

Prerequisites: chapter 10. The template body is the chapter-10 movie with placeholders.

Step 1 — Save the movie as a template#

Two ways:

1. Dashboard. Paste the chapter-10 movie JSON into the visual editor → click Save as template → give it a name (e.g. real-estate-listing-v1).
2. API. Submit POST /v2/templates with the body:

{
  "name": "real-estate-listing-v1",
  "movie": { ... the full chapter-10 JSON, minus the variables block ... }
}

The response contains a template ID — typically a short alphanumeric string. Keep it.

Step 2 — Call the template#

Once saved, the rendering payload shrinks. Submit POST /v2/movies with the template ID plus the variables for the specific property:

{
  "template": "real-estate-listing-v1",
  "variables": {
    "address": "47 Cedar Avenue, Seattle, WA",
    "price": "$1,200,000",
    "bedrooms": "5",
    "agent_name": "Pat Morgan"
  }
}

The server loads the template, merges the request's variables on top, and renders the result. Same output as chapter 10 — just less payload.

Step 3 — Override the resolution / quality at call time#

A few movie-level fields are taken from the request, not the template: resolution, width, height, quality, exports, and client-data. This lets one template power vertical-9:16 and horizontal-16:9 outputs without duplicating the JSON.

{
  "template": "real-estate-listing-v1",
  "resolution": "instagram-story",
  "quality": "medium",
  "variables": {
    "address": "47 Cedar Avenue, Seattle, WA",
    "price": "$1,200,000",
    "bedrooms": "5"
  }
}

Step 4 — Submit from your favourite SDK#

The call looks identical to chapter 7, only the body differs:

curl -X POST https://api.json2video.com/v2/movies \
  -H "x-api-key: $JSON2VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "real-estate-listing-v1",
    "variables": {
      "address": "47 Cedar Avenue, Seattle, WA",
      "price": "$1,200,000",
      "bedrooms": "5"
    }
  }'

await fetch("https://api.json2video.com/v2/movies", {
  method: "POST",
  headers: {
    "x-api-key": process.env.JSON2VIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template: "real-estate-listing-v1",
    variables: {
      address: "47 Cedar Avenue, Seattle, WA",
      price: "$1,200,000",
      bedrooms: "5",
    },
  }),
});

import os, requests
requests.post(
    "https://api.json2video.com/v2/movies",
    headers={"x-api-key": os.environ["JSON2VIDEO_API_KEY"]},
    json={
        "template": "real-estate-listing-v1",
        "variables": {
            "address": "47 Cedar Avenue, Seattle, WA",
            "price": "$1,200,000",
            "bedrooms": "5",
        },
    },
)

<?php
$body = json_encode([
    "template" => "real-estate-listing-v1",
    "variables" => [
        "address" => "47 Cedar Avenue, Seattle, WA",
        "price" => "$1,200,000",
        "bedrooms" => "5",
    ],
]);
$ch = curl_init("https://api.json2video.com/v2/movies");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("JSON2VIDEO_API_KEY"), "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);

The complete final JSON#

A render request that uses the template — replace the body of POST /v2/movies with this:

{
  "template": "real-estate-listing-v1",
  "resolution": "full-hd",
  "variables": {
    "address": "123 Oak Street",
    "price": "$849,000",
    "bedrooms": "4",
    "agent_name": "Jordan Lee"
  }
}

Expected output#

Same 16-second video as chapter 10. The win is on the client side: your CRM only needs to remember the template ID plus the per-property variables. Sample render: tutorial-11.mp4 (placeholder).

What you learned#

• A template is the movie JSON stored on the server, identified by an ID.
• POST /v2/movies accepts either a full movie body or a template + variables body.
• Request-level fields (resolution, quality, exports, client-data) override the stored template.
• Templates are managed via the Dashboard or the /v2/templates endpoint family.

Going further#

For a deeper dive on the dashboard side, see Guides → Dashboard → Templates.

Previous chapter / Next chapter#

← 10. Variables · 12. Expressions →