YouTube

Video Types

YouTube automatically detects content type based on duration:

Duration	Type	Notes
≤ 3 minutes	YouTube Shorts	Vertical format, no custom thumbnails via API
> 3 minutes	Regular Video	Supports custom thumbnails

Video Requirements

Property	Shorts	Regular Video
Max Duration	3 minutes	12 hours
Min Duration	1 second	1 second
Max File Size	256 GB	256 GB
Formats	MP4, MOV, AVI, WMV, FLV, 3GP	MP4, MOV, AVI, WMV, FLV, 3GP
Aspect Ratio	9:16 (vertical)	16:9 (horizontal)
Resolution	1080 × 1920 px	1920 × 1080 px (1080p)

Recommended Specs

Property	Shorts	Regular Video
Resolution	1080 × 1920 px	3840 × 2160 px (4K)
Frame Rate	30 fps	24-60 fps
Codec	H.264	H.264 or H.265
Audio	AAC, 128 kbps	AAC, 384 kbps
Bitrate	10 Mbps	35-68 Mbps (4K)

Upload Example

{
  "content": "My Latest Video\n\nIn this video, I share my thoughts on...\n\n#tutorial #howto",
  "mediaItems": [
    { "url": "https://example.com/video.mp4" }
  ],
  "platforms": [
    {
      "platform": "youtube",
      "accountId": "acc_123",
      "platformSpecificData": {
        "title": "My Latest Video",
        "visibility": "public"
      }
    }
  ]
}

Title and Description

Property	Limit	Notes
Title	100 characters	Defaults to first line of content
Description	5000 characters	Full content used

The content field becomes the video description. The title is either:

Specified in platformSpecificData.title
Auto-extracted from first line of content
"Untitled Video" as fallback

Visibility Options

Control who can see your video:

Visibility	Description
`public`	Anyone can search and watch (default)
`unlisted`	Only people with link can watch
`private`	Only you and shared users

{
  "platformSpecificData": {
    "visibility": "unlisted"
  }
}

Custom Thumbnails

For regular videos (>3 min), add a custom thumbnail:

{
  "mediaItems": [
    {
      "url": "https://example.com/video.mp4",
      "thumbnail": {
        "url": "https://example.com/thumbnail.jpg"
      }
    }
  ]
}

Thumbnail Requirements

Property	Requirement
Format	JPEG, PNG, GIF
Max Size	2 MB
Resolution	1280 × 720 px (16:9)
Min Width	640 px

Note: Custom thumbnails are not supported for Shorts via API.

First Comment

Add an automatic pinned comment:

{
  "platformSpecificData": {
    "firstComment": "Thanks for watching! Don't forget to subscribe. What topics should I cover next? 👇"
  }
}

Max 10,000 characters
Posted immediately after upload
Can include links

Scheduled Videos

When scheduling a YouTube video:

Video uploads immediately with specified visibility
Stays in that state until scheduled time
At scheduled time, may change to "public" if originally set

{
  "scheduledFor": "2024-12-25T10:00:00Z",
  "platforms": [
    {
      "platform": "youtube",
      "platformSpecificData": {
        "visibility": "private"
      }
    }
  ]
}

Supported Formats

Format	Extension	Notes
MPEG-4	.mp4	Recommended
QuickTime	.mov	Well supported
AVI	.avi	Supported
WMV	.wmv	Windows Media
FLV	.flv	Flash Video
3GPP	.3gp	Mobile format
WebM	.webm	Supported
MPEG-PS	.mpg	Supported

Common Issues

Video stuck processing

Large videos (>1 GB) may take 30+ minutes to process. Use scheduled posts for async handling.

Wrong video type detected

Shorts: ≤3 min + vertical aspect ratio
Regular: >3 min OR horizontal aspect ratio
Ensure aspect ratio matches intent

Thumbnail rejected

Must be exactly 16:9 aspect ratio
Max 2 MB file size
Min 640 px width
Not available for Shorts

Audio issues

Use AAC codec
Avoid copyright-protected music
Ensure audio bitrate is at least 128 kbps

Resolution too low

Minimum recommended:

Shorts: 720 × 1280 px
Regular: 1280 × 720 px (720p)

On this page