youtube-api

name: youtube-api description: | Manage YouTube videos programmatically via the YouTube Data API v3 — upload video files, upload custom thumbnails, update video metadata (titles, descriptions, tags), and query video/channel info without touching YouTube Studio's browser UI. Use this skill whenever the user wants to: upload a local video file to YouTube; set, update, or change a YouTube video's thumbnail from a local image file; batch-set thumbnails across multiple videos; update video titles, descriptions, or tags programmatically; query their channel's video list; or do anything involving the YouTube Data API. Triggers: "upload to youtube", "upload video", "set thumbnail", "upload thumbnail", "change thumbnail", "YouTube API", "batch thumbnails", "update video title", "update video description", "youtube metadata", or any reference to programmatically managing YouTube videos. Also use when the browser-based YouTube Studio upload is unreliable or slow. license: MIT compatibility: | Requires Python 3.8+ with google-api-python-client, google-auth-oauthlib, and google-auth. Works on macOS, Linux, and Windows. Requires a Google Cloud project with YouTube Data API v3 enabled and OAuth 2.0 Desktop credentials. One-time browser-based OAuth consent required on the user's local machine before headless/Cowork use. metadata: author: swyxio version: "1.0" last-updated: "2026-03-28" primary-tools: YouTube Data API v3, Python, Google OAuth 2.0

YouTube API

Manage YouTube videos programmatically — uploads, thumbnails, metadata, and queries — via the YouTube Data API v3, completely bypassing the YouTube Studio browser UI.

Why This Skill Exists

YouTube Studio's browser UI is unreliable for bulk operations and awkward for automation. The file picker for thumbnails is flaky, editing metadata for multiple videos is tedious, and browser uploads can stall or reset. This skill wraps the YouTube Data API v3 with OAuth2 authentication and persistent token caching, so once set up, uploads and follow-up edits are fully scriptable — including across Cowork VM resets.

Prerequisites

Python Dependencies

pip install google-api-python-client google-auth-oauthlib google-auth --break-system-packages

Google Cloud Project Setup (One-Time)

If the user hasn't set up YouTube API credentials yet, walk them through this. It takes about 5 minutes:

1. Create/select a Google Cloud Project

   • Go to console.cloud.google.com
   • Create a new project or select an existing one

2. Enable the YouTube Data API v3

   • Navigate to APIs & Services → Library
   • Search for "YouTube Data API v3" → click Enable

3. Configure the OAuth consent screen

   • Go to Google Auth Platform → Overview → "Get started"
   • App name: anything (e.g., "YouTube API Tool")
   • User support email: select the user's Google email
   • Audience: External
   • Contact email: the user's email
   • Agree to the Google API Services User Data Policy → Create

4. Add the user as a test user (critical — the app stays in Testing mode)

   • Go to Google Auth Platform → Audience
   • Under "Test users", click "+ Add users"
   • Add the Google email associated with their YouTube channel
   • Save

5. Create OAuth 2.0 credentials

   • Go to Google Auth Platform → Clients → "+ Create client"
   • Application type: Desktop app
   • Name: anything (e.g., "YouTube API Tool")
   • Click Create
   • Download the JSON — this is the client_secret.json file

6. Store the credentials

   On macOS/Linux (standard):

   mkdir -p ~/.config/youtube-api
   mv ~/Downloads/client_secret_*.json ~/.config/youtube-api/client_secret.json
   

   For Cowork persistence (survives VM resets):

   mkdir -p ~/Downloads/.youtube-api
   mv ~/Downloads/client_secret_*.json ~/Downloads/.youtube-api/client_secret.json
   

7. Run the first-time OAuth flow (must happen on the user's local machine — a browser opens)

   python <skill-path>/scripts/setup_auth.py
   

   This opens a browser for Google OAuth consent. The user signs in, authorizes the app, and a token.pickle is cached alongside the client_secret.json. After this, all subsequent runs (including in Cowork) are fully automatic.

   When the consent screen appears, it will warn the app is "unverified" — this is normal for testing mode. Click "Advanced" → "Go to [app name] (unsafe)" → allow access.

Where Credentials Live

The scripts auto-detect the best credential location:

Both client_secret.json and token.pickle must be in the same directory. The scripts check the Cowork path first, then fall back to the standard path.

Operations

Set Thumbnails

Upload custom thumbnail images to one or more YouTube videos.

Single video:

python <skill-path>/scripts/set_thumbnail.py --video-id VIDEO_ID --thumbnail /path/to/image.jpg

Batch mode:

python <skill-path>/scripts/set_thumbnail.py \
  --batch VIDEO_ID_1:/path/to/thumb1.jpg VIDEO_ID_2:/path/to/thumb2.jpg

Thumbnail requirements:

• Max size: 2 MB (compress with convert input.jpg -resize 1280x720 -quality 85 output.jpg)
• Formats: JPEG (recommended), PNG
• Dimensions: 1280x720 recommended (16:9 aspect ratio)

Upload Videos

Upload a finished local video file directly to YouTube.

python <skill-path>/scripts/upload_video.py --file /path/to/video.mp4 --privacy unlisted

Optional metadata at upload time:

python <skill-path>/scripts/upload_video.py \
  --file /path/to/video.mp4 \
  --privacy unlisted \
  --title "Video Title" \
  --description "Optional description" \
  --tags "tag1,tag2"

Update Video Metadata

Update titles, descriptions, and/or tags for one or more videos.

Single video:

python <skill-path>/scripts/update_metadata.py --video-id VIDEO_ID \
  --title "New Title" \
  --description "New description" \
  --tags "tag1,tag2,tag3"

Batch mode (from JSON):

python <skill-path>/scripts/update_metadata.py --batch updates.json

Where updates.json looks like:

[
  {"video_id": "abc123", "title": "New Title", "description": "New desc"},
  {"video_id": "def456", "tags": ["tag1", "tag2"]}
]

Only the fields you specify are updated — everything else is preserved.

List Channel Videos

Query the authenticated user's channel for their uploaded videos.

python <skill-path>/scripts/list_videos.py [--max-results 50]

Returns video IDs, titles, publish dates, and thumbnail URLs. Useful for building batch operations.

API Quota

• thumbnails.set: 50 units per call
• videos.update: 50 units per call
• videos.list: 1 unit per call
• search.list: 100 units per call
• Default daily quota: 10,000 units → ~200 thumbnail uploads or metadata updates per day
• If you hit quota limits, wait until the next day or request a quota increase in Google Cloud Console → APIs & Services → Quotas

Troubleshooting

Integration with Other Pipelines

This skill works well as the final step in content pipelines. For example, after generating thumbnails with an image generation tool:

# Generate thumbnails, then upload them
python <skill-path>/scripts/set_thumbnail.py \
  --batch \
  xUy0vno25k0:~/Downloads/thumb_feb4.jpg \
  LJFL6bYyGHg:~/Downloads/thumb_feb13.jpg \
  s5bTZfYUcac:~/Downloads/thumb_feb18.jpg