YouTube

YouTube is supported in V1 for OAuth connect, video publishing, and scheduling. Videos are required — Shorts are auto-classified by YouTube for qualifying vertical uploads. Analytics, inbox/comment sync, and community posts are not available yet.

Connect an account

Generate a Connect Link with "platform": "youtube"
Send the url to your user — they authorize via Google OAuth
After OAuth completes, the profile appears via GET /v1/profiles

Self-hosted deployments

Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET on your API server. Register redirect URI {NEXT_PUBLIC_API_URL}/v1/oauth/callback/youtube on your Google Cloud OAuth client (prod and local tunnel URLs as needed).

Scopes requested: youtube.upload, youtube.readonly, and youtube.force-ssl (first comment and playlist attach). After widening scopes, reconnect existing YouTube profiles so users re-consent.

Uploads from unverified API projects created after July 28, 2020 are restricted to private visibility, regardless of the requested privacyStatus. Complete YouTube API project verification before expecting public or unlisted uploads.

Content types

Video upload

A publicly reachable video URL is required in mediaUrls.

{
  "text": "A deep dive into our architecture...\n\n#API #buildinpublic",
  "profileIds": ["prof_yt123"],
  "mediaUrls": ["https://cdn.example.com/episode-12.mp4"],
  "overrides": {
    "youtube": {
      "title": "How We Built a Unified Social Media API",
      "privacyStatus": "public",
      "categoryId": "28",
      "tags": ["api", "youtube"]
    }
  }
}

Shorts

Upload a vertical video (typically 9:16, under ~3 minutes). YouTube classifies qualifying videos as Shorts automatically — no special flag or content type is required.

{
  "text": "Quick explainer on API rate limits. #Shorts #API",
  "profileIds": ["prof_yt123"],
  "mediaUrls": ["https://cdn.example.com/short-clip.mp4"],
  "overrides": {
    "youtube": {
      "title": "60 seconds to understand rate limiting"
    }
  }
}

Platform overrides

Field	Description
`title`	Video title (max 100 chars). Defaults to the first 100 characters of post text
`text`	Description override (otherwise uses base `text`)
`privacyStatus`	`public` (default), `private`, or `unlisted`. Unverified API projects created after July 28, 2020 can only upload as private until verification completes
`categoryId`	YouTube category ID (default `22` People & Blogs). Common: `10` Music, `20` Gaming, `24` Entertainment, `27` Education, `28` Science & Tech
`tags`	Array of tags (each ≤100 chars; combined ≤500 after dedupe)
`madeForKids`	COPPA self-declared made-for-kids flag (`selfDeclaredMadeForKids`)
`containsSyntheticMedia`	Disclose realistic AI / synthetic (altered) media
`playlistId`	Add the video to this playlist after upload
`thumbnailUrl`	Custom thumbnail image URL (regular videos; channel must allow custom thumbnails)
`firstComment`	Top-level comment posted after upload (also supported at post level)

Playlists

List playlists for a connected YouTube profile:

GET /v1/profiles/:profileId/youtube-playlists

Use a returned playlist id as overrides.youtube.playlistId when creating a post. Aether does not auto-apply a default playlist — attach is explicit per publish. Creating or deleting playlists is not supported.

First comment

Pass firstComment at the post level or in overrides.youtube to publish a top-level comment immediately after the video uploads (uses YouTube commentThreads.insert).

Scheduling

Pass scheduledFor with an optional timezone — same as other platforms. Aether holds the post and uploads when the schedule fires, using the privacyStatus you set (default public). Native YouTube publishAt (upload as private then platform-side publish) is not used in this phase.

Quota

Video uploads (videos.insert) use a dedicated default allocation of 100 upload calls per day. Other YouTube Data API endpoints draw from the shared 10,000-unit daily quota.

Operation	Approx. cost
Video upload (`videos.insert`)	Dedicated bucket: 100 uploads/day (1 unit each)
Playlist attach (`playlistItems.insert`)	~50 units (shared pool)

Exceeding limits returns a platform error (e.g. quotaExceeded or uploadLimitExceeded).

Not available for YouTube yet

Feature	Status
Post and account analytics	Connector does not implement metrics fetch yet
Inbox / comment sync & moderation	Not supported
Community posts	Not supported via YouTube Data API in Aether
Post-publish metadata update API	Planned (title/tags/thumb/playlist on existing videos)
Native YouTube `publishAt`	Not implemented — use Aether `scheduledFor`

Verification checklist

After configuring your Google OAuth client and API env vars:

Dashboard → Profiles → Connect → YouTube
Complete OAuth → profile appears with platform: "youtube"
Publish a short vertical clip (Shorts) and a longer video
Optional: set thumbnailUrl, playlistId, and firstComment
Optional: schedule a post ~10 minutes ahead and confirm it publishes on time

Symptom	Fix
YouTube grayed out in connect dialog	Rebuild `@aether/shared` after adding `youtube` to `V1_PLATFORMS`
Redirect error	Google redirect URI must match `{NEXT_PUBLIC_API_URL}/v1/oauth/callback/youtube` exactly
First comment or playlist attach fails with permission error	Reconnect the profile to grant `youtube.force-ssl`
Thumbnail ignored / fails	Channel must be verified for custom thumbnails; failures are non-fatal after a successful upload

See MCP Server and Node.js SDK for connect and publish examples.

YouTube

On this page