Skip to main content

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.

Key Differences from Image Generation

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.

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​

PropertyTypeRequiredDescription
widthnumber❌Video width in pixels (default: 1280)
heightnumber❌Video height in pixels (default: 720)
fpsnumber❌Frames per second (default: 25)
formatstring❌Output format: mp4, mov (default: mp4)
fastboolean❌Enable fast processing mode (e.g. for a preview)
clipsarray✅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​

PropertyTypeRequiredDescription
durationnumber❌Clip duration in seconds (uses default if omitted)
layersarray✅Layers that appear during this clip
transitionobject❌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:

Token Usage​

Video generation requires more tokens than image generation due to the computational complexity. For details, see our Rate Limits & Tokens guide.