# 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
- **AI coding agents**: MCP server for Claude Code, Cursor and VS Code — `npm install -g @json2video/cli` then `json2video mcp install claude` — [guide](https://json2video.com/docs/v2/help-for-ai-agents/mcp-server)

## Pricing (USD, as of October 2026)

- 1 credit = 1 second of rendered video. Managed voice-overs (Azure, ElevenLabs) and auto subtitles currently use 0 credits. Failed renders are not charged.
- Free: 600 credits (10 minutes), watermarked, no credit card.
- One-off packs (credits never expire): $49.95 for 7,200 credits (120 min); $99.95 for 15,600 credits (260 min).
- Subscriptions: Professional $49.95/month for 12,000 credits (200 min); Startup $99.95/month for 30,000 credits (500 min); Hobby yearly $199.50/year for 3,000 credits a month (50 min). Higher-volume plans in the dashboard.
- When credits run out, rendering stops; there are no overage charges.
- Details: https://json2video.com/pricing/

## Comparisons

- JSON2Video vs Creatomate: https://json2video.com/how-to/creatomate-alternative/
- JSON2Video vs Shotstack: https://json2video.com/how-to/shotstack-alternative/
- JSON2Video vs Remotion (including Claude Code workflows): https://json2video.com/how-to/remotion-alternative/
- JSON2Video vs Bannerbear: https://json2video.com/how-to/bannerbear-alternative/

## Video APIs

- Video APIs: the six types and how to choose (hub, providers, prices and MCP support): https://json2video.com/video-api/
- Video Editing API: render videos from JSON, with JSON2Video, Creatomate, Shotstack, Plainly, Bannerbear and Remotion compared: https://json2video.com/video-api/video-editing-api/
- AI Video Generation API: Veo, Runway, Luma and Kling compared, with the cost of a 30-second video: https://json2video.com/video-api/video-generation-api/
- Video Processing API: FFmpeg APIs and transcoding (MediaConvert, Coconut, Rendi, Transloadit) compared, with FFmpeg vs JSON2Video examples: https://json2video.com/video-api/video-processing-api/
- Video Hosting API: Mux, api.video, Cloudflare Stream, Bunny and Cloudinary compared, with free tiers and a worked cost example: https://json2video.com/video-api/video-hosting-api/
- Live Streaming API: Mux Live, Amazon IVS, Cloudflare Stream and Daily compared, with a worked cost example: https://json2video.com/video-api/video-streaming-api/
- Video Conferencing API: Twilio, Daily, LiveKit and Agora compared per participant-minute: https://json2video.com/video-api/video-conferencing-api/

## Making videos with Claude

- Can Claude make videos? Every way to do it (Claude Code, MCP servers, Claude Motion, generators) and what each costs: https://json2video.com/claude-video/
- Video editing with Claude Code: FFmpeg, Remotion and the JSON2Video MCP server (`json2video mcp install claude`): https://json2video.com/claude-video/claude-video-editing/
- Video generation with Claude: AI clips from Runway and Veo, assembled into finished videos: https://json2video.com/claude-video/claude-video-generation/
- Claude animation: Claude Motion, Remotion, HyperFrames and JSON2Video components compared: https://json2video.com/claude-video/claude-animation/
- Best video MCP servers for Claude: which work in claude.ai, Claude Code and Claude Desktop: https://json2video.com/claude-video/video-mcp-servers/

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