YouTube Video Uploader

Uploads a video from a URL to your own YouTube channel using the official YouTube Data API. It sets the title, description, tags, hashtags, privacy, schedule, and an optional custom thumbnail in one run. Built to be the publish step of an automated video pipeline (render somewhere, drop the file on a CDN, point this actor at the URL), but it works fine for one-off scheduled uploads too.

How it works

You give it a public URL to the video file and your Google OAuth credentials. The actor downloads the file to its temp disk, authenticates with your refresh token, and calls youtube.videos.insert (followed by thumbnails.set if you passed a thumbnail). Nothing about your channel is stored beyond the run.

Preview the output shape (sample mode)

Run it without any credentials to get one clearly-labeled _demo sample row showing the exact output shape — no upload is performed and nothing touches your channel. The sample row is still a dataset row, so it is billed like one upload ($0.05); see Pricing below. As soon as you supply real OAuth credentials (or YouTube cookies for the browser method) it performs a real upload. You can also force the preview with the demoMode checkbox.

Input

Field	Required	Notes
videoUrl	yes	Public direct URL to the video file (.mp4/.mov). You host it (S3, a CDN, Apify key-value store). It must be reachable without auth.
title	yes	YouTube title. Trimmed to 100 characters.
description	no	Video description. Hashtags are appended to the end.
tags	no	Up to 30 tags. Anything past 30 is dropped.
hashtags	no	Appended to the description as #tag. Non-alphanumeric characters are stripped.
privacyStatus	no	public, unlisted, or private. Defaults to private (the actor fails closed — it never publishes publicly unless you ask).
publishAt	no	ISO datetime to auto-publish. YouTube requires the video to be private for scheduling, so if you set publishAt with public/unlisted the actor auto-coerces privacy to private (and logs it) so your schedule actually works.
thumbnailUrl	no	Public URL to a thumbnail image. Custom thumbnails require a verified channel; if the API rejects it the upload still succeeds.
categoryId	no	YouTube category ID. Defaults to 22 (People & Blogs). 24 = Entertainment, 23 = Comedy, 27 = Education.
madeForKids	no	Declares the video as made for kids (COPPA). Defaults to false.
clientId / clientSecret / refreshToken	yes (for the API method)	Your own Google OAuth credentials from Google Cloud Console. The refresh token must carry the youtube.upload scope. Marked secret.

The actor also has a browser method that drives YouTube Studio with exported login cookies. It works locally but tends to hit Google's session anti-fraud on cloud runs, so the API method is the default and the one to use for anything unattended. If you do use it, supply your own proxy servers in proxyUrls (a residential exit matching your usual country helps) — the Apify proxy groups offered here are datacenter only.

Output

One dataset record per run. The useful fields are videoId, watchUrl (the youtu.be link), privacyStatus (the privacy YouTube actually stored, read back from the API), requestedPrivacy, privacyOverridden (true if YouTube forced a different privacy — usually an unverified project), scheduledFor (null unless you set publishAt), thumbnailSet, and uploadSeconds. ok: true means the insert returned a video ID. A keyless/demoMode run returns a single row flagged _demo: true with a _notice explaining nothing was uploaded.

Example

{
  "videoUrl": "https://cdn.example.com/clips/episode-12.mp4",
  "title": "How the Roman aqueducts actually worked",
  "description": "A short breakdown of gravity-fed water systems.",
  "tags": ["history", "engineering", "rome"],
  "hashtags": ["shorts", "history"],
  "privacyStatus": "private",
  "publishAt": "2026-06-15T14:00:00Z",
  "categoryId": "27",
  "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "refreshToken": "YOUR_REFRESH_TOKEN"
}

Pricing

$0.05 per upload row returned, plus $0.005 per gigabyte of run memory each time a run starts — $0.01 per start at the 2 GB default. Flat rate: no volume tiers, no plan gates, no subscription.

A run that fails before the upload completes writes no dataset row and is not charged the $0.05 — you pay for uploads that actually publish. The demoMode / no-credentials preview does write one labelled sample row, and that row is billed at the same $0.05, so use it to check the output shape once rather than on a loop.

Your Google Cloud quota is separate and free: videos.insert costs roughly 100 of the default 10,000 daily units.

Before your first PUBLIC upload (read this)

Two Google-side requirements catch almost everyone:

1. Publish your OAuth consent screen. New API projects start in "Testing" mode, where refresh tokens expire after 7 days. Move the consent screen to "In production" so your refresh token keeps working. (If a run fails with "refresh token is expired or revoked", this is why.)
2. Verify your project to publish public videos. On an UNVERIFIED Google Cloud project, YouTube forces every uploaded video to private regardless of what you request — this is the single most common reason a "public" upload shows up as private. Request the YouTube API compliance audit to lift this. This actor reads back the privacy YouTube actually stored and, if it was overridden, sets privacyOverridden: true in the output and logs a warning, so you'll know.
3. Quota. As of Dec 2025, videos.insert costs ~100 units; the default free quota is ~10,000 units/day, i.e. roughly 100 uploads/day. Heavier use needs a quota increase.

Notes

You need your own Google OAuth credentials. There is no shared app. Create an OAuth client in Google Cloud Console with the YouTube Data API enabled, then generate a refresh token with the youtube.upload scope.

Errors are actionable

Credential and quota problems return a plain-English message naming the fix (expired refresh token, missing channel, quota exhausted, forbidden/missing scope) rather than a raw stack trace. For the browser method, a failed login/step saves a screenshot and the page HTML to the run's key-value store and references them in the error so you can see exactly where it broke.

Browser method (best-effort)

The optional browser method drives YouTube Studio with your exported login cookies instead of the API. It is best-effort: fresh-context logins from cloud/datacenter IPs frequently trip Google's "verify it's you" checkpoint, so prefer the API method for anything unattended. To use it, export your YouTube session (a cookies array or a Playwright storageState) with a "Cookie-Editor" / "Get cookies.txt" extension covering both .youtube.com and .google.com, or via npx playwright codegen --save-storage, and paste it into cookies. For the proxy, put your own proxy servers in proxyUrls (a residential exit matching your usual country helps most) — they are used exactly as supplied. The Apify proxy groups this Actor offers are datacenter only: an upload pushes the whole video file through the proxy, and metered groups (RESIDENTIAL, GOOGLE_SERP) bill per gigabyte, so a request for one is swapped for datacenter and reported back in the output as proxyNotice.