Quickstart

Render your first video in five minutes. This guide assumes you have a JSON2Video account and a terminal or runtime with HTTP client capabilities.

1. Get your API key

Sign in to the Dashboard and copy your API key from the API Keys page. Full instructions are in the API keys guide. All requests to the API must include the key in the x-api-key header.

2. Create your first movie

Send a POST /v2/movies request with a minimal JSON body. The example below produces a 5-second 1920x1080 video with a single line of text.

curl -X POST "https://api.json2video.com/v2/movies" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "full-hd",
    "scenes": [
      {
        "duration": 5,
        "elements": [
          { "type": "text", "text": "Hello, JSON2Video!", "style": "001" }
        ]
      }
    ]
  }'

const res = await fetch("https://api.json2video.com/v2/movies", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    resolution: "full-hd",
    scenes: [
      {
        duration: 5,
        elements: [
          { type: "text", text: "Hello, JSON2Video!", style: "001" },
        ],
      },
    ],
  }),
});

const { project } = await res.json();
console.log("Project ID:", project);

import requests

res = requests.post(
    "https://api.json2video.com/v2/movies",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "resolution": "full-hd",
        "scenes": [
            {
                "duration": 5,
                "elements": [
                    {"type": "text", "text": "Hello, JSON2Video!", "style": "001"}
                ],
            }
        ],
    },
)

project = res.json()["project"]
print("Project ID:", project)

<?php
$body = json_encode([
    "resolution" => "full-hd",
    "scenes" => [[
        "duration" => 5,
        "elements" => [
            ["type" => "text", "text" => "Hello, JSON2Video!", "style" => "001"]
        ]
    ]]
]);

$ch = curl_init("https://api.json2video.com/v2/movies");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Project ID: " . $response["project"];

The response contains a project ID. Rendering is asynchronous — use the ID to poll for the result.

3. Poll for the result

Send GET /v2/movies?project={id} every few seconds. The response includes a status field that progresses through queued, running, and finally done or error.

curl "https://api.json2video.com/v2/movies?project=YOUR_PROJECT_ID" \
  -H "x-api-key: YOUR_API_KEY"

async function waitForMovie(projectId) {
  while (true) {
    const res = await fetch(
      `https://api.json2video.com/v2/movies?project=${projectId}`,
      { headers: { "x-api-key": "YOUR_API_KEY" } }
    );
    const data = await res.json();
    if (data.movie.status === "done") return data.movie;
    if (data.movie.status === "error") throw new Error(data.movie.message);
    await new Promise(r => setTimeout(r, 3000));
  }
}

const movie = await waitForMovie("YOUR_PROJECT_ID");
console.log("Video URL:", movie.url);

import time, requests

def wait_for_movie(project_id):
    while True:
        res = requests.get(
            "https://api.json2video.com/v2/movies",
            params={"project": project_id},
            headers={"x-api-key": "YOUR_API_KEY"},
        )
        movie = res.json()["movie"]
        if movie["status"] == "done":
            return movie
        if movie["status"] == "error":
            raise RuntimeError(movie.get("message"))
        time.sleep(3)

movie = wait_for_movie("YOUR_PROJECT_ID")
print("Video URL:", movie["url"])

<?php
function waitForMovie($projectId) {
    while (true) {
        $ch = curl_init("https://api.json2video.com/v2/movies?project=" . $projectId);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $movie = json_decode(curl_exec($ch), true)["movie"];
        curl_close($ch);

        if ($movie["status"] === "done")  return $movie;
        if ($movie["status"] === "error") throw new Exception($movie["message"]);
        sleep(3);
    }
}

$movie = waitForMovie("YOUR_PROJECT_ID");
echo "Video URL: " . $movie["url"];

4. Get your video

When status is done, the response includes the rendered video at movie.url — a public, CDN-hosted MP4 you can download, embed, or pass to another service. The response also contains the final duration, the resolution, and the rendering time.

{
  "success": true,
  "movie": {
    "status": "done",
    "url": "https://assets.json2video.com/clients/abc.../renders/2026-05-12-12345.mp4",
    "duration": 5,
    "size": { "width": 1920, "height": 1080 }
  }
}

Next steps

Build a real project step-by-step in the Tutorials.
Learn every JSON property in the Reference.

Quickstart#

1. Get your API key#

2. Create your first movie#

3. Poll for the result#

4. Get your video#