# JSON2Video

> JSON2Video is a REST API to create and edit videos programmatically using JSON. Automate video production at scale for marketing, social media, and personalized content.

JSON2Video lets you define video content, layout, and style using a simple JSON structure. Submit the JSON to the API, and get back a rendered MP4 video. It supports templates with variables, AI-generated voiceovers, automatic subtitles, and animated components.

## Key Features

- **Programmatic video creation**: Define videos as JSON and render them via API
- **Template system**: Create reusable templates with variables for dynamic content
- **AI voiceover generation**: Text-to-speech in multiple languages (Azure, ElevenLabs)
- **Auto subtitles**: Automatic transcription and subtitle overlay
- **Animated components**: Pre-built HTML5/CSS animated text, shapes, and elements
- **Multiple resolutions**: SD, HD, Full HD, square, Instagram, Twitter formats, or custom sizes
- **Export options**: Webhook, FTP/SFTP, S3, email delivery
- **No-code integrations**: Make.com, Zapier, n8n, Pabbly
- **SDKs**: PHP and Node.js

## API Overview

- Base URL: `https://api.json2video.com/v2`
- Authentication: API key via `x-api-key` header
- Format: JSON request and response bodies

### Endpoints

#### POST /movies — Create a new video

Submit a Movie JSON object to start a rendering job. Returns a `project` ID to track status.

```bash
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": [{
      "elements": [{
        "type": "video",
        "src": "https://example.com/video.mp4"
      }]
    }]
  }'
```

Response:
```json
{
  "success": true,
  "project": "PROJECT_ID",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

#### GET /movies — Check video status

Poll with `?project=PROJECT_ID` until `status` is `done` or `error`.

Response when done:
```json
{
  "success": true,
  "movie": {
    "status": "done",
    "url": "https://assets.json2video.com/clients/.../video.mp4",
    "duration": 30.5,
    "width": 1920,
    "height": 1080
  },
  "remaining_quota": { "time": 1807 }
}
```

Status values: `pending`, `running`, `done`, `error`.

### Using Templates

Instead of defining a full movie JSON, reference a saved template and pass variables:

```json
{
  "template": "TEMPLATE_ID",
  "variables": {
    "title": "Breaking News",
    "subtitle": "Something happened today",
    "background_video": "https://example.com/bg.mp4"
  }
}
```

## Movie JSON Schema

### Movie Object

The root object defining the video. Required property: `scenes`.

| Property | Type | Description |
|---|---|---|
| `resolution` | string | Preset size: `sd`, `hd`, `full-hd`, `squared`, `instagram-story`, `instagram-feed`, `twitter-landscape`, `twitter-portrait`, `custom` |
| `width` | integer | Width in pixels (50–3840). Only when resolution is `custom` |
| `height` | integer | Height in pixels (50–3840). Only when resolution is `custom` |
| `quality` | string | `low`, `medium`, `high` (default: `high`) |
| `scenes` | array | Array of Scene objects (required) |
| `elements` | array | Global elements that overlay all scenes |
| `template` | string | Template ID to use |
| `variables` | object | Key-value pairs for template variables |
| `exports` | array | Export configurations (webhook, FTP, etc.) |
| `draft` | boolean | If true, adds watermark (default: true) |
| `cache` | boolean | Use cached version if available (default: true) |
| `client-data` | object | Custom metadata passed through to responses and webhooks |

### Scene Object

A segment of the video. Scenes play sequentially and cannot overlap.

| Property | Type | Description |
|---|---|---|
| `elements` | array | Array of Element objects |
| `duration` | number | Duration in seconds. `-1` = auto-fit to elements |
| `background-color` | string | Hex color or `transparent` (default: `#000000`) |
| `condition` | string | Expression; scene is skipped if false or empty |
| `transition` | object | Transition effect between scenes (25+ styles) |
| `variables` | object | Scene-local variables |

### Element Types

Elements are the building blocks of scenes. Each has a `type` property.

#### `video` — Video clip
| Property | Type | Description |
|---|---|---|
| `src` | string | URL of the video file |
| `duration` | string/number | Duration: seconds, `"auto"`, or `"container"` |
| `start` | number | Start time in seconds |
| `x`, `y` | number | Position coordinates |
| `width`, `height` | number | Dimensions |
| `crop` | object | Crop settings |
| `zoom` | number | Ken Burns zoom effect |

#### `image` — Static image
| Property | Type | Description |
|---|---|---|
| `src` | string | URL of the image file |
| `duration` | string/number | Duration |
| `x`, `y` | number | Position |
| `width`, `height` | number | Dimensions |
| `zoom` | number | Ken Burns zoom effect |

#### `text` — Text overlay
| Property | Type | Description |
|---|---|---|
| `text` | string | The text content |
| `font-family` | string | Font name |
| `font-size` | number | Font size in pixels |
| `font-color` | string | Text color (hex) |
| `x`, `y` | number | Position |
| `width`, `height` | number | Text box dimensions |
| `text-align` | string | Alignment: `left`, `center`, `right` |
| `background-color` | string | Background color |

#### `component` — Animated HTML5 component
| Property | Type | Description |
|---|---|---|
| `component` | string | Component ID from the library |
| `settings` | object | Component-specific settings |
| `duration` | string/number | Duration |
| `x`, `y` | number | Position |
| `width`, `height` | number | Dimensions |

#### `audio` — Audio track
| Property | Type | Description |
|---|---|---|
| `src` | string | URL of the audio file |
| `duration` | string/number | Duration |
| `start` | number | Start time |
| `volume` | number | Volume level (0–1) |

#### `voice` — AI text-to-speech voiceover
| Property | Type | Description |
|---|---|---|
| `text` | string | Text to convert to speech |
| `voice` | string | Voice ID (Azure or ElevenLabs) |
| `provider` | string | TTS provider (`azure`, `elevenlabs`) |
| `duration` | string/number | Duration |

#### `audiogram` — Audio waveform visualization
| Property | Type | Description |
|---|---|---|
| `style` | string | Visualization style |
| `color` | string | Waveform color |
| `x`, `y` | number | Position |
| `width`, `height` | number | Dimensions |

#### `subtitles` — Automatic subtitles
| Property | Type | Description |
|---|---|---|
| `style` | string | Subtitle style/template |
| `font-family` | string | Font name |
| `font-size` | number | Font size |
| `font-color` | string | Text color |

### Common Element Properties

All visual elements share these properties:

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique element identifier |
| `type` | string | Element type (required) |
| `condition` | string | Conditional rendering expression |
| `duration` | string/number | Duration in seconds, `"auto"`, or `"container"` |
| `start` | number | Start time within the scene (seconds) |
| `extra-time` | number | Additional time after element ends |
| `z-index` | number | Stacking order |
| `x`, `y` | number | Position (top-left origin, like CSS) |

## Basic Concepts

- **Movie**: The final rendered video, defined by a JSON document
- **Scene**: A sequential segment of the movie. Scenes are rendered independently and chained together
- **Element**: Content components within scenes (video, image, text, audio, etc.)
- **Duration**: Elements can use fixed seconds, `"auto"` (natural length), or `"container"` (match parent)
- **Coordinates**: CSS-like positioning with (0,0) at top-left
- **Layering**: Later elements in the array render on top of earlier ones
- **Caching**: Assets and scenes are cached to optimize rendering time

## Integration Methods

- **HTTP API**: Direct REST calls from any language
- **Node.js SDK**: `npm install json2video` — [GitHub](https://github.com/json2video)
- **PHP SDK**: Composer package — [GitHub](https://github.com/json2video)
- **No-code**: Make.com, Zapier, n8n, Pabbly integrations

## Links

- Website: https://json2video.com
- Documentation: https://json2video.com/docs/v2/getting-started
- API Reference: https://json2video.com/docs/v2/api-reference
- Movie JSON Schema: https://json2video.com/docs/v2/api-reference/json-syntax
- Templates Guide: https://json2video.com/docs/v2/api-reference/json-syntax/movie
- Element Types: https://json2video.com/docs/v2/api-reference/json-syntax/element
- Tutorials: https://json2video.com/docs/v2/getting-started/how-it-works
- AI Voiceover: https://json2video.com/docs/tutorial/ai-generation/ai-voiceover-generation
- AI Image Generation: https://json2video.com/docs/tutorial/ai-generation/ai-image-generation
- Subtitle Guide: https://json2video.com/docs/tutorial/subtitle-elements/examples
- Template Variables: https://json2video.com/docs/tutorial/templates/working-with-variables
- Conditional Elements: https://json2video.com/docs/tutorial/templates/conditional-elements-in-templates
- Transitions: https://json2video.com/docs/tutorial/transitions
- Make.com Integration: https://json2video.com/docs/v2/no-code-integrations/makecom
- Get API Key: https://json2video.com/get-api-key
- Dashboard: https://json2video.com/dashboard
- Visual Editor: https://json2video.com/tools/visual-editor
- GitHub: https://github.com/json2video