Youtube api

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:

Environment	Config directory	Persists across sessions?
Cowork	/sessions/*/mnt/Downloads/.youtube-api/	Yes (on user's real machine)
Standard	~/.config/youtube-api/	Yes

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

Error	Cause	Fix
"token has been expired or revoked"	OAuth token expired beyond refresh	Delete token.pickle from the config directory (shown at startup) and re-run setup_auth.py
"quotaExceeded"	Hit daily API quota	Wait until tomorrow or request a quota increase
"forbidden" or "thumbnailsNotAccessible"	Account lacks custom thumbnail permission	Verify the YouTube account is in good standing with custom thumbnails enabled
"The caller does not have permission"	Not a test user on the OAuth consent screen	Add the Google email as a test user in Google Auth Platform → Audience
"fileNotFound" on image	Bad file path	Check the file path; the script validates before uploading
Image too large	Over 2 MB	Compress: convert input.jpg -resize 1280x720 -quality 85 output.jpg
Browser doesn't open for OAuth	Running in headless/Cowork environment	Run setup_auth.py on your local machine first, then copy token.pickle to the Cowork config directory

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