Skip to main content

​
Overview

Postiz provides YouTube video upload and scheduling with comprehensive metadata support, including titles, descriptions, tags, thumbnails, and privacy settings.
YouTube requires exactly one video attachment. Text-only posts or multiple videos are not supported.

​
Authentication

YouTube uses Google OAuth 2.0 with extensive permissions.
1

Connect YouTube

Click “Connect YouTube” in Integrations
2

Sign in with Google

Authenticate with your Google account
3

Grant Permissions

Authorize all YouTube and YouTube Analytics permissions
4

Select Channel

Choose which YouTube channel to connect

​
Required Permissions

  • https://www.googleapis.com/auth/userinfo.profile - User profile
  • https://www.googleapis.com/auth/userinfo.email - User email
  • https://www.googleapis.com/auth/youtube - Full YouTube access
  • https://www.googleapis.com/auth/youtube.force-ssl - HTTPS access
  • https://www.googleapis.com/auth/youtube.readonly - Read data
  • https://www.googleapis.com/auth/youtube.upload - Upload videos
  • https://www.googleapis.com/auth/youtubepartner - Partner features
  • https://www.googleapis.com/auth/yt-analytics.readonly - Analytics

​
Supported Features

​
Video Upload

Title:
  • Required field
  • Keep concise for best display
Description:
  • Up to 5000 characters
  • Supports timestamps and links
  • First 2-3 lines appear in search
Tags:
  • Multiple tags supported
  • Improves discoverability
  • Max 500 characters total

​
Post Settings Schema

{
  title: string,              // Video title (required)
  type: "public" | "unlisted" | "private",
  selfDeclaredMadeForKids: "yes" | "no",
  tags: Array<{label: string}>,
  thumbnail: {                // Optional, requires verified account
    path: string             // URL to thumbnail image
  }
}

​
Upload Process

1

Download Video

Video is fetched from the provided URL as a stream
2

Upload to YouTube

Video uploaded via YouTube Data API v3 with metadata
3

Set Thumbnail

If provided, custom thumbnail is uploaded (requires verified account)
4

Return URL

YouTube video URL returned: youtube.com/watch?v={videoId}
Video uploads are processed in real-time with streaming upload for efficient handling of large files.

​
Channel Management

Manage multiple YouTube channels:
  • List all channels you have access to
  • Select specific channel for posting
  • Channel name, picture, and subscriber count displayed
  • Support for brand accounts

​
Analytics

​
Channel-Level Analytics

Track overall channel performance:
  • Views: Total video views
  • Estimated Minutes Watched: Watch time
  • Average View Duration: Engagement metric
  • Average View Percentage: Completion rate
  • Subscribers Gained: New subscribers
  • Subscribers Lost: Unsubscribes
  • Likes: Total likes
Data broken down by day over your selected time period.

​
Video-Level Analytics

Detailed metrics per video:
  • Views: Total views
  • Likes: Like count
  • Comments: Comment count
  • Favorites: Favorite count
{
  "label": "Views",
  "percentageChange": 0,
  "data": [
    {
      "total": "1523",
      "date": "2024-03-15"
    }
  ]
}

​
Rate Limits

YouTube Upload Quotas:
  • Daily upload quota limits apply
  • Default: ~6 uploads per day
  • Quota resets at midnight Pacific Time
  • Max 200 concurrent jobs in Postiz

​
Error Handling

Common YouTube errors:
ErrorCauseSolution
invalidTitleTitle too longShorten video title
failedPreconditionThumbnail too largeReduce thumbnail size under 2MB
uploadLimitExceededDaily quota exceededWait until quota resets tomorrow
youtubeSignupRequiredNo YouTube channelCreate YouTube channel first
youtube.thumbnailAccount not verifiedVerify account or remove thumbnail
UnauthorizedToken expiredReconnect YouTube account
Thumbnail Verification: Custom thumbnails require a verified YouTube account. New accounts must verify via phone before uploading custom thumbnails.

​
Best Practices

Title Optimization

Front-load keywords in the first 60 characters for search and mobile

Description Format

Include timestamps, links, and full context in the first 200 characters

Thumbnail Quality

Use high-quality 1280x720 thumbnails with clear text and faces

Tag Strategy

Use 5-8 relevant tags mixing broad and specific keywords

​
Troubleshooting

If you hit the upload limit:
  • YouTube allows ~6 uploads per day for new channels
  • Quota increases with channel history and standing
  • Resets at midnight Pacific Time
  • Request quota increase through Google Cloud Console
Thumbnail issues:
  • Account must be verified (phone verification)
  • File size must be under 2MB
  • Use JPG or PNG format
  • Recommended size: 1280x720px
  • Remove thumbnail if account not verified
If authentication fails:
  • Ensure YouTube channel exists (not just Google account)
  • All OAuth permissions must be granted
  • Token may have expired - reconnect
  • Check for any Google account restrictions
After upload:
  • YouTube needs time to process video (HD/4K takes longer)
  • Video may not be immediately available
  • Processing status shown in YouTube Studio
  • Usually completes within 30 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us