Aspect Ratio Transformation

Transform your videos to any aspect ratio for different platforms and use cases. VideoCascade provides intelligent scaling, cropping, and padding to ensure your content looks great everywhere.

Supported Aspect Ratios

Aspect Ratio	Dimensions Example	Common Use Cases
`original`	No change	Keep original dimensions
`16:9`	1920x1080	YouTube, TV, widescreen
`9:16`	1080x1920	TikTok, Instagram Reels, Stories
`1:1`	1080x1080	Instagram Post, Facebook
`4:5`	1080x1350	Instagram Portrait Post
`4:3`	1440x1080	Traditional TV, presentations
`21:9`	2560x1080	Ultrawide, cinematic

Resize Modes

Control how your video is resized to fit the target aspect ratio:

Cover (Default)

Scales video to fill entire frame, cropping excess content.

Best for: When you want to fill the frame completely without black bars.

┌─────────────────┐
│                 │
│   ┌─────────┐   │  Original (16:9)
│   │  Video  │   │
│   └─────────┘   │
│                 │
└─────────────────┘

      ↓ Cover to 1:1

┌───────────┐
│           │
│   Video   │  Cropped sides
│ (cropped) │
│           │
└───────────┘

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/video.mp4',
    aspectRatio: '1:1',
    resizeMode: 'cover'  // Fill frame, crop excess
  }),
});

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'fileUrl': 'https://example.com/video.mp4',
        'aspectRatio': '1:1',
        'resizeMode': 'cover'
    }
)

Contain

Scales video to fit within frame, adding padding (letterbox/pillarbox) as needed.

Best for: When you want to show entire video without cropping.

┌─────────────────┐
│                 │
│   ┌─────────┐   │  Original (16:9)
│   │  Video  │   │
│   └─────────┘   │
│                 │
└─────────────────┘

      ↓ Contain to 1:1

┌──────────┐
│██████████│  Black padding
├──────────┤
│  Video   │
├──────────┤
│██████████│  Black padding
└──────────┘

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/video.mp4',
    aspectRatio: '1:1',
    resizeMode: 'contain',  // Fit entire video, add padding
    backgroundColor: '#000000'  // Padding color
  }),
});

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'fileUrl': 'https://example.com/video.mp4',
        'aspectRatio': '1:1',
        'resizeMode': 'contain',
        'backgroundColor': '#000000'
    }
)

Stretch

Stretches video to exact dimensions, distorting aspect ratio.

Best for: When precise dimensions matter more than maintaining proportions (rare).

┌─────────────────┐
│                 │
│   ┌─────────┐   │  Original (16:9)
│   │  Video  │   │
│   └─────────┘   │
│                 │
└─────────────────┘

      ↓ Stretch to 1:1

┌──────────┐
│          │
│  Video   │  Stretched vertically
│  (tall)  │
│          │
└──────────┘

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/video.mp4',
    aspectRatio: '1:1',
    resizeMode: 'stretch'  // Distort to fit
  }),
});

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'fileUrl': 'https://example.com/video.mp4',
        'aspectRatio': '1:1',
        'resizeMode': 'stretch'
    }
)

Warning: Stretch mode distorts video proportions. People and objects will appear wider or taller. Use with caution.

Background Color (Padding)

When using contain mode, customize the padding color with backgroundColor:

// Black padding (default)
{
  aspectRatio: '9:16',
  resizeMode: 'contain',
  backgroundColor: '#000000'
}

// White padding
{
aspectRatio: '9:16',
resizeMode: 'contain',
backgroundColor: '#FFFFFF'
}

// Custom brand color
{
aspectRatio: '1:1',
resizeMode: 'contain',
backgroundColor: '#FF6B6B' // Coral red
}

# Black padding (default)
{
    'aspectRatio': '9:16',
    'resizeMode': 'contain',
    'backgroundColor': '#000000'
}

# White padding
{
    'aspectRatio': '9:16',
    'resizeMode': 'contain',
    'backgroundColor': '#FFFFFF'
}

# Custom brand color
{
    'aspectRatio': '1:1',
    'resizeMode': 'contain',
    'backgroundColor': '#FF6B6B'  # Coral red
}

interface AspectRatioRequest {
  fileUrl: string;
  aspectRatio: '16:9' | '9:16' | '1:1' | '4:5' | '4:3' | '21:9' | 'original';
  resizeMode: 'cover' | 'contain' | 'stretch';
  backgroundColor: string;  // Hex color code
}

// Black padding (default)
const request1: AspectRatioRequest = {
fileUrl: 'https://example.com/video.mp4',
aspectRatio: '9:16',
resizeMode: 'contain',
backgroundColor: '#000000'
};

// White padding
const request2: AspectRatioRequest = {
fileUrl: 'https://example.com/video.mp4',
aspectRatio: '9:16',
resizeMode: 'contain',
backgroundColor: '#FFFFFF'
};

Color Format: Use 6-digit hex codes only (e.g., #FF0000). Format #RGB or #RRGGBBAA not supported.

Platform-Specific Guides

YouTube (16:9)

Optimize for YouTube's standard widescreen format:

{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '16:9',
  resizeMode: 'cover',
  compressionQuality: 90
}

Recommended Resolution: 1920x1080 (Full HD) or 3840x2160 (4K)

TikTok / Instagram Reels (9:16)

Optimize for vertical mobile video:

// Portrait video from landscape source
const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/landscape-video.mp4',
    aspectRatio: '9:16',
    resizeMode: 'cover',  // Crop to fill vertical frame
    compressionQuality: 85
  }),
});

# Portrait video from landscape source
response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'fileUrl': 'https://example.com/landscape-video.mp4',
        'aspectRatio': '9:16',
        'resizeMode': 'cover',
        'compressionQuality': 85
    }
)

Recommended Resolution: 1080x1920

TikTok Tips: - Use cover mode to fill vertical frame - Keep important content in center (safe zone) - Max duration: 10 minutes (3 minutes recommended)

Instagram Feed Post (1:1 or 4:5)

Square or portrait format for Instagram feed:

// Square post (classic Instagram)
{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '1:1',
  resizeMode: 'cover',
  compressionQuality: 85
}

// Portrait post (more screen space)
{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '4:5',
  resizeMode: 'cover',
  compressionQuality: 85
}

Recommended Resolutions:

Square (1:1): 1080x1080
Portrait (4:5): 1080x1350

Instagram Stories (9:16)

Full-screen vertical stories:

{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '9:16',
  resizeMode: 'cover',
  compressionQuality: 80
}

Recommended Resolution: 1080x1920 Max Duration: 60 seconds per story

Facebook Video (1:1 or 16:9)

Square for feed, widescreen for Watch:

// Feed video (square, auto-plays in feed)
{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '1:1',
  resizeMode: 'cover'
}

// Facebook Watch (widescreen)
{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '16:9',
  resizeMode: 'cover'
}

Twitter/X (16:9 or 1:1)

Widescreen or square:

{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '16:9',
  resizeMode: 'cover',
  compressionQuality: 85
}

Max Duration: 2 minutes 20 seconds (140 seconds)

LinkedIn (1:1 or 16:9)

Professional content, square or widescreen:

{
  fileUrl: 'https://example.com/video.mp4',
  aspectRatio: '1:1',  // Better engagement in feed
  resizeMode: 'cover',
  compressionQuality: 90
}

Combining with Other Features

Transform aspect ratio along with other processing:

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/video.mp4',
    // Aspect ratio transformation
    aspectRatio: '9:16',
    resizeMode: 'cover',
    backgroundColor: '#000000',
    // Audio processing
    removeSilence: true,
    normalizeAudio: true,
    // Segment removal
    removeSegments: [
      { startTime: 0, endTime: 5 },
      { startTime: 55, endTime: 60 }
    ],
    // Quality control
    compressionQuality: 90,
    outputFormat: 'mp4'
  }),
});

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'fileUrl': 'https://example.com/video.mp4',
        # Aspect ratio transformation
        'aspectRatio': '9:16',
        'resizeMode': 'cover',
        'backgroundColor': '#000000',
        # Audio processing
        'removeSilence': True,
        'normalizeAudio': True,
        # Segment removal
        'removeSegments': [
            {'startTime': 0, 'endTime': 5},
            {'startTime': 55, 'endTime': 60}
        ],
        # Quality control
        'compressionQuality': 90,
        'outputFormat': 'mp4'
    }
)

interface CompleteRequest {
  fileUrl: string;
  aspectRatio: '9:16';
  resizeMode: 'cover' | 'contain' | 'stretch';
  backgroundColor: string;
  removeSilence: boolean;
  normalizeAudio: boolean;
  removeSegments: Array<{ startTime: number; endTime: number }>;
  compressionQuality: number;
  outputFormat: 'mp4';
}

const request: CompleteRequest = {
fileUrl: 'https://example.com/video.mp4',
aspectRatio: '9:16',
resizeMode: 'cover',
backgroundColor: '#000000',
removeSilence: true,
normalizeAudio: true,
removeSegments: [
{ startTime: 0, endTime: 5 },
{ startTime: 55, endTime: 60 }
],
compressionQuality: 90,
outputFormat: 'mp4'
};

Best Practices

1. Choose the Right Resize Mode

Use Cover When:

You want maximum screen coverage
Cropping edges is acceptable
Content is centered in frame

Use Contain When:

You must show entire video
No content can be cropped
Padding is acceptable (e.g., interviews)

Avoid Stretch:

People/objects will look distorted
Only use for abstract content or graphics

2. Match Platform Requirements

// ✅ Good: Optimized for each platform
const tiktokRequest = {
  aspectRatio: '9:16',
  resizeMode: 'cover'
};

const youtubeRequest = {
  aspectRatio: '16:9',
  resizeMode: 'cover'
};

const instagramRequest = {
  aspectRatio: '1:1',
  resizeMode: 'cover'
};

3. Preserve Quality

Use high compression quality when transforming:

{
  aspectRatio: '9:16',
  resizeMode: 'cover',
  compressionQuality: 95  // Minimize quality loss
}

4. Consider Safe Zones

When using cover mode, keep important content centered:

┌─────────────────┐
│  [CROP ZONE]    │  ← May be cropped
│                 │
│   [SAFE ZONE]   │  ← Always visible
│                 │
│  [CROP ZONE]    │  ← May be cropped
└─────────────────┘

5. Test Before Batch Processing

Test aspect ratio transformations on one video before processing many:

// Test with sample video
const testResponse = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    /* ... */
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/test-video.mp4',
    aspectRatio: '9:16',
    resizeMode: 'cover',
  }),
});

// Verify result looks good, then process all videos

Common Use Cases

Repurpose YouTube Video for TikTok

{
  fileUrl: 'https://example.com/youtube-video-16x9.mp4',
  aspectRatio: '9:16',
  resizeMode: 'cover',  // Crop to vertical
  removeSegments: [
    { startTime: 0, endTime: 10 },  // Remove intro
    { startTime: 290, endTime: 300 }  // Remove outro
  ],
  compressionQuality: 85
}

Create Multi-Platform Versions

Process same video for multiple platforms:

const videoUrl = 'https://example.com/master-video.mp4';

// YouTube version
const youtubeVersion = await processVideo({
fileUrl: videoUrl,
aspectRatio: '16:9',
resizeMode: 'cover',
compressionQuality: 90
});

// TikTok/Reels version
const tiktokVersion = await processVideo({
fileUrl: videoUrl,
aspectRatio: '9:16',
resizeMode: 'cover',
compressionQuality: 85
});

// Instagram post version
const instagramVersion = await processVideo({
fileUrl: videoUrl,
aspectRatio: '1:1',
resizeMode: 'cover',
compressionQuality: 85
});

// Facebook version
const facebookVersion = await processVideo({
fileUrl: videoUrl,
aspectRatio: '1:1',
resizeMode: 'cover',
compressionQuality: 85
});

interface PlatformConfig {
  platform: string;
  aspectRatio: string;
  resizeMode: 'cover' | 'contain';
  compressionQuality: number;
}

const platforms: PlatformConfig[] = [
  { platform: 'youtube', aspectRatio: '16:9', resizeMode: 'cover', compressionQuality: 90 },
  { platform: 'tiktok', aspectRatio: '9:16', resizeMode: 'cover', compressionQuality: 85 },
  { platform: 'instagram', aspectRatio: '1:1', resizeMode: 'cover', compressionQuality: 85 },
];

const videoUrl = 'https://example.com/master-video.mp4';

const versions = await Promise.all(
  platforms.map(config =>
    processVideo({
      fileUrl: videoUrl,
      aspectRatio: config.aspectRatio,
      resizeMode: config.resizeMode,
      compressionQuality: config.compressionQuality
    })
  )
);

Interview Video with Letterbox

Show full interview without cropping speakers:

{
  fileUrl: 'https://example.com/interview-4x3.mp4',
  aspectRatio: '16:9',
  resizeMode: 'contain',  // Show full frame
  backgroundColor: '#1a1a1a',  // Dark gray padding
  normalizeAudio: true,
  compressionQuality: 95
}