Video Generation Overview
JsonCut's video generation system allows you to create professional videos programmatically using JSON configurations. Generate promotional videos, educational content, social media videos, and more with a flexible clip and layer-based system.
Video generation uses a different structure and property system than image generation. While some concepts are similar, many properties work differently or are video-specific. Always refer to this video generation documentation rather than assuming image generation properties apply.
You can reference public HTTP(S) URLs for image and video layers (properties like path, url, or src). Supported extensions:
- Images:
.png,.jpg,.jpeg - Videos:
.mp4,.webm,.mov
At job creation, JsonCut downloads, validates, uploads to storage, and rewrites the config to secure relative paths. Public URLs are not supported for fonts; use uploads (fontPath) or googleFont.
Basic Structure
Every video generation job follows this basic structure:
{
"type": "video",
"config": {
"width": 1920,
"height": 1080,
"fps": 30,
"format": "mp4",
"clips": [
{
"duration": 3,
"layers": [
// Your layers go here
]
}
]
}
}
Core Properties
| Property | Type | Required | Description |
|---|---|---|---|
width | number | ❌ | Video width in pixels (default: 1280) |
height | number | ❌ | Video height in pixels (default: 720) |
fps | number | ❌ | Frames per second (default: 25) |
format | string | ❌ | Output format: mp4, mov (default: mp4) |
fast | boolean | ❌ | Enable fast processing mode (e.g. for a preview) |
clips | array | ✅ | Array of clip objects that make up the video |
Clip-Based System
Unlike images, videos are built using clips - segments of video content that play sequentially. Each clip has a duration and contains layers that define what appears during that time segment.
{
"clips": [
{
"duration": 3,
"layers": [
{
"type": "fill-color",
"color": "#007acc"
},
{
"type": "title",
"text": "Welcome to JsonCut",
"fontSize": 60
}
]
},
{
"duration": 2,
"layers": [
{
"type": "video",
"path": "/video/2024-01-15/user123/background.mp4"
}
]
}
]
}
Clip Properties
| Property | Type | Required | Description |
|---|---|---|---|
duration | number | ❌ | Clip duration in seconds (uses default if omitted) |
layers | array | ✅ | Layers that appear during this clip |
transition | object | ❌ | Transition effect to next clip |
Video Layer Types
Videos support various layer types, each designed for specific content:
- Video - Display video files with cutting and scaling options
- Image - Static images that appear throughout the clip duration
- Image Overlay - Images positioned over other content
- Title - Large headline text with custom positioning
- Subtitle - Smaller text for captions and descriptions
- News Title - Breaking news style titles with backgrounds
- Title Background - Titles with colored background blocks
- Slide-in Text - Animated text with slide-in effects
- Audio - Audio tracks tied to specific clips
- Detached Audio - Audio tracks independent of clip timing
- Fill Color - Solid color backgrounds
- Gradients - Linear and radial color gradients
- Rainbow Colors - Animated rainbow gradient effects
- Pause - Black screen pauses
Position System
Video layers use a flexible positioning system supporting both absolute and relative coordinates:
{
"type": "title",
"text": "Centered Title",
"position": "center"
}
{
"type": "image-overlay",
"path": "/image/2024-01-15/user123/logo.png",
"position": { "x": 0.9, "y": 0.1, "originX": "right", "originY": "top" },
"width": 0.2,
"height": 0.2
}
Position Options
String positions: center, top, bottom, top-left, top-right, center-left, center-right, bottom-left, bottom-right
Object positions: Relative coordinates (0-1) with optional origin points
Working with Defaults
Define default properties for consistency across your video:
{
"type": "video",
"config": {
"width": 1920,
"height": 1080,
"defaults": {
"duration": 4,
"layer": {
"fontPath": "/font/2025-09-12/cmejszvz00000t5afm8qcr6bq/1e5d2d4d-4e20-4fa9-81f5-706ab04f435d.ttf"
},
"layerType": {
"title": {
"fontSize": 64,
"textColor": "#ffffff",
"position": "center"
},
"subtitle": {
"fontSize": 32,
"textColor": "#cccccc"
}
}
},
"clips": [
{
"layers": [
{
"type": "title",
"text": "Uses default styling",
"zoomDirection": null
}
]
}
]
}
}
Simple Example
Here's a complete example that creates a basic promotional video:
{
"type": "video",
"config": {
"width": 1280,
"height": 720,
"fps": 30,
"audioFilePath": "/audio/2025-09-12/cmejszvz00000t5afm8qcr6bq/4154c1b3-659a-4e8c-81af-d07cebd8394a.mp3",
"loopAudio": true,
"outputVolume": 0.7,
"defaults": {
"duration": 3
},
"clips": [
{
"layers": [
{
"type": "fill-color",
"color": "#667eea"
},
{
"type": "title",
"text": "Welcome to JsonCut",
"fontSize": 64,
"textColor": "#ffffff",
"position": "center"
}
]
},
{
"duration": 5,
"layers": [
{
"type": "image",
"path": "/image/2025-09-12/cmejszvz00000t5afm8qcr6bq/1a57c011-3765-49be-9840-c193647f7df8.png",
"resizeMode": "cover",
"zoomDirection": "in",
"zoomAmount": 0.1
},
{
"type": "subtitle",
"text": "Create professional videos with JSON",
"textColor": "#ffffff",
"fontSize": 28
}
]
},
{
"duration": 4,
"layers": [
{
"type": "video",
"path": "/video/2025-09-12/cmejszvz00000t5afm8qcr6bq/60f0f7be-7146-4762-8274-1013ffd25271.mp4",
"resizeMode": "contain",
"cutFrom": 0,
"cutTo": 4
},
{
"type": "title",
"text": "Easy to Use",
"textColor": "#ffffff",
"fontSize": 42
}
],
"transition": {
"name": "circleopen",
"duration": 1.2
}
},
{
"layers": [
{
"type": "radial-gradient",
"colors": ["#ff6b6b", "#4ecdc4"]
},
{
"type": "title",
"text": "Get Started Today",
"fontSize": 56,
"textColor": "#ffffff",
"position": "center"
},
{
"type": "subtitle",
"text": "Start creating amazing videos now",
"textColor": "#ffffff",
"fontSize": 24
}
]
}
]
}
}
Audio Integration
Videos support multiple audio options:
Background Audio
{
"type": "video",
"config": {
"audioFilePath": "/audio/2024-01-15/user123/background-music.mp3",
"loopAudio": true,
"outputVolume": 0.8,
"clips": [...]
}
}
Audio Tracks
{
"type": "video",
"config": {
"audioTracks": [
{
"path": "/audio/2024-01-15/user123/voiceover.mp3",
"mixVolume": 0.9,
"start": 2
}
],
"clips": [...]
}
}
Output Formats
JsonCut supports multiple video formats optimized for different platforms:
MP4 (Default)
- Best for: General purpose, web, social media
- Compatibility: Excellent across all platforms
- File size: Balanced compression and quality
MOV
- Best for: Apple ecosystem, professional editing
- Compatibility: Native Apple format
- File size: Higher quality, larger files
{
"type": "video",
"config": {
"format": "mov",
"width": 1920,
"height": 1080,
"clips": [...]
}
}
Transitions
Create smooth transitions between clips:
{
"clips": [
{
"duration": 3,
"layers": [...],
"transition": {
"name": "fade",
"duration": 1.5
}
}
]
}
Available transitions include: fade, slideLeft, slideRight, wipeLeft, wipeRight, circleopen, blur, and many more.
Performance Considerations
- Clip duration: Longer videos require more processing time
- Layer complexity: Limit layers per clip for optimal performance
- Video files: Compress input videos appropriately
- Transitions: Complex transitions increase processing time
- Audio: Multiple audio tracks can impact performance
Next Steps
Ready to create your first video? Explore these topics:
- Layer Types - Complete guide to all video layer types
- Clips & Transitions - Master video structure and transitions
- Audio & Sound - Add background music, voiceovers, and effects
- Examples - Real-world video creation examples
Token Usage
Video generation requires more tokens than image generation due to the computational complexity. For details, see our Rate Limits & Tokens guide.